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Foreword 


The  Amiga  once  widely  considered  a  little  more  than  just  a  game 
machine,  has  now  become  a  worthy  and  serious  rival  to  the  PC  and  the 
Mac. 

Both  the  professional  quality  of  software  and  the  improvement  of  the 
Amiga's  operating  system  have  contributed  to  its  "coming  of  age".  With 
the  appearance  of  Kickstart  2.0  (AmigaOS  2.0),  the  user  interface  has 
attained  a  professional  level.  It's  natural  that  this  professionalism  should 
carry  over  into  the  quality  of  software.  Much  knowledge  about 
hardware  and  software  is  required  to  master  the  Amiga.  Assuming  you're 
acquainted  with  the  basics  of  programming,  and  the  detailed  information 
about  how  the  system  works,  this  book  will  provide  you  with  the 
necessary  professional  know-how.  The  scope  of  the  book  alone 
indicates  the  enormous  amount  of  knowledge  and  effort  that  have  gone 
into  its  preparation.  To  address  as  many  aspects  of  the  Amiga  as  possible, 
three  authors  have  contributed  their  knowledge  and  experience. 
Correspondingly,  the  book  is  divided  into  three  parts: 


Parti 
Part  2 
Part  3 


System  Programming  (Stefan  Maelger) 

ARexx  (Christian  Kuhnert) 

A3000  Intern  (Johannes  Schemmel) 


These  sections  can  be  read  individually  or  consecutively;  their  sequence 
is  not  important.  Each  one  constitutes  in  itself  a  useful  learning  tool  and  a 
guide  for  later  reference. 

We  wish  you  many  enjoyable  and  enlightening  hours  with  "Amiga 
Intern."  Maybe  you  will  soon  be  publishing  professional  software  for  the 
Amiga. 

We  are  grateful  to  Commodore  and  especially  to  Dr.  Kittel  for  their  kind 
support. 
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Parti 


System 
Programming 


Part  1  -  Introduction 


The  Amiga  operating  system  is  modular.  Multitasking  is  achieved  simply 
and  with  near-optimal  memory  utilization  through  the  use  of  libraries  and 
virtual  devices.  Only  what  is  needed  is  saved  in  memory,  and  several 
programs  can  share  simultaneous  access  to  system  resources.  The 
capability  of  Intertasking,  or  interprogram  communication  over  message 
ports,  is  one  of  the  many  features  of  the  Amiga's  powerful  and  flexible 
operating  system  that  you  will  read  about  in  this  book.  At  first,  learning 
all  these  capabilities  won't  seem  easy.  The  first  part  of  the  book,  "System 
Programming",  should  give  you  the  necessary  background  information 
for  system  programming  in  the  AmigaOS  2.0  environment. 

Author:  Stefan  Maelger 


1.1  Inside  AmigaOS  2.x 


1 .    Kickstart  2.04 


The  new  AmigaOS  (Amiga  Operating  System)  is  here.  It  has  taken  some 
time  to  reach  its  present  state  of  development.  However,  the  wait  has 
been  worth  it  because  this  operating  system  is  better  than  any 
predecessor.  This  contains  51 2K,  which  makes  this  system  more  powerful 
than  any  other  system. 


1.1      Inside  AmigaOS  2.x 


AmigaOS  2.x  is  based  on  the  hardware  environment  of  the  Amiga  3000 
(i.e.,  on  the  68030  and  68882  processors)  and  the  new  ECS  (Enhanced 
Chip  Set)  custom  chips.  It  must  be  distinguished  from  previous  beta 
versions  based  on  the  Amiga  1000,  which  are  capable  of  calling  only  part 
of  the  power  that  the  Amiga  3000  operating  system  provides.  These  beta 
versions,  released  to  program  developers  who  did  not  own  a  3000,  were 
intended  for  compatibility  testing  only. 

Similar  to  the  preceding  versions,  AmigaOS  2.x  is  a  multitasking 
operating  system,  running  several  programs  simultaneously.  By  dividing 
memory  into  two  distinct  types  and  utilizing  the  DMA  (co-processor) 
concept,  it  is  capable  of  actual  simultaneous  memory  access  (i.e.,  true 
hardware  multitasking).  The  Amiga's  main  program  is  the  Input  task.  It 
manages  all  input  and  transfers  control  to  various  system  routines.  For 
example,  the  complex  display-controller  called  Intuition.  Commands  are 
passed  from  Intuition  to  the  Input  task,  where,  at  intervals  of  l/50th  of  a 
second,  they  are  eligible  for  execution.  Since  Intuition  tasks  are 
accomplished  almost  exclusively  by  the  Input  task,  and  the  work  of  this 
program  is  synchronized  by  clock  pulses,  all  performance  tests  using 
Intuition  are  meaningless.  But  with  speed,  the  availability  of  static  32  bit 
RAM  on  the  non-multiplexed  bus  (free  Fast  RAM)  will  enhance 
performance  considerably,  by  enabling  the  processor  to  be  switched  to 
burst-mode  for  top-speed  access  of  the  68030's  data  and  instruction 
cache. 

To  find  out  how  the  operating  system  is  put  together,  let's  try  taking  it 
apart. 


1.  Kickstart  2.04 


1.1.1  Reset  Capabilities 


Begin  with  a  "cold  start"  by  switching  on  the  3000.  Press  both  mouse 
buttons  at  once,  and  you  will  be  moved  to  the  Operating  System  Menu. 
Here  you  can  select  the  operating  system  you  want  to  work  with  and 
specify  the  source  from  which  it  should  be  loaded.  For  example,  an  old 
version  of  the  operating  system  can  be  loaded  from  the  (hard)  drive  into 
a  RAM  storage  area.  The  68030's  integrated  MMU  logically  shifts  this 
area  to  the  normal  operating  system  address  and  protects  it  against 
overwrite. 

Now  the  current  operating  system's  normal  reset  routine,  which  can  also 
be  invoked  by  the  sequence  <ctrQ,lft-Amiga,rt-Amiga>,  is  initiated.  Under 
AmigaOS  2.x,  any  external  or  internal  expansions  are  immediately 
recognized  and  incorporated  into  the  system  (this  was  not  the  case  with 
earlier  versions).  The  operating  system  checks  hardware  and  memory  and 
builds  the  tables  for  routines  (error  handling)  and  interrupts.  All  base  data 
structures  containing  variable  values  are  then  set  up. 

Pressing  both  mouse  buttons  again  will  take  you  to  the  Boot  Menu.  This 
screen  allows  you  to  select  the  logical  or  physical  drive  from  which 
booting  will  take  place.  This  drive  will  be  referred  to  as  SYS  (system 
directory).  For  other  Amigas,  even  before  the  start  of  DOS,  all  logical 
drives  are  recognized  and  drive  names  established.  The  execution  of  the 
Startup  sequence  can  also  be  disabled.  This  can  be  an  advantage  for  CLI 
users,  since  the  InitialCLI  itself  is  now  a  complete  shell,  providing  a 
convenient  and  easy-to-use  platform  for  the  Command  Line  Interface. 

Now  the  Device  Operating  System  (DOS)  is  started  and  the  work  shell 
initialized.  To  save  time  and  avoid  problems  selecting  the  right  monitor 
driver,  the  windows  aren't  opened  until  the  Workbench  is  activated  or 
output  in  an  InitialCLI  window  requires  it. 
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1.1.2  The  Main  Units  of  AmigaOS  2.x 

The  Amiga  Operating  system  is  designed  in  modules.  Considering  the 
size  of  the  entire  system  and  that  the  Amiga  is  a  multitasking  device,  this 
is  a  great  advantage.  The  modular  design  makes  the  system  more  flexible 
and  easier  to  change.  The  main  units  can  be  divided  into  four  groups: 
Libraries,  Devices,  Resources  and  Special.  Libraries  are  simply  collections 
of  routines  of  a  certain  type  or  application.  Devices  serve  as  logical 
device  drivers  and  may  perform  one  or  more  tasks.  Resources  include 
base  routines  which  usually  manage  access  to  certain  resources  and 
exclude  them  from  or  reserve  them  for  other  programs. 

The  modules  are  initialized  according  to  their  priorities. 

The  following  modules  are  found  in  AmigaOS  2.4  ROM  in  the  order  of 
their  initialization: 
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Address 

Pri 

Typ 

Name 

Vers. 

Date 

$00f83cc0 

+110 

Library 

expansion 

37.23 

(3/15/91) 

$00f800b6 

+105 

Library 

exec 

37.52 

(3/15/91) 

$00f83cda 

+105 

Special 

diag  init 

$00fbb09a 

+103 

Library 

utility 

37.3 

(2/13/91) 

$00faba14 

+100 

Resource 

potgo 

37.4 

(1/28/91) 

$00f889e0 

+80 

Resource 

da 

37.4 

(3/15/91) 

$00f98dac 

+80 

Resource 

filesysres 

37.1 

(1/12/91) 

$00f8f3bc 

+70 

Resource 

disk 

37.1 

(1/9/91) 

$00fab964 

+70 

Resource 

misc 

37.1 

(1/8/91) 
(3/14/91) 

$00fbbb50 

+65 

Library 

graphics 

37.20 

$00faebd8 

+60 

Device 

gameport 

37.8 

(1/28/91) 

$00fb8540 

+50 

Device 

timer 

37.57 

(3/14/91) 

$00f85890 

+45 

Resource 

battclock 

37.3 

(3/11/91) 

$00faec02 

+45 

Device 

keyboard 

37.8 

(1/28/91) 

$00f862d0 

+44 

Resource 

battmem 

37.3 

(3/4/91) 

$00»a6984 

+40 

Library 

keymap 

37.2 

(1/8/91) 

$00faec2c 

+40 

Device 

input 

37.8 

(1/28/91) 

$00fa76c4 

+31 

Library 

layers 

37.7 

(3/13/91) 

$00fae054 

+25 

Device 

ramdrive 

37.3 

(1/9/91) 

$00fb936c 

+20 

Device 

trackdisk 

37.3 

(3/13/91) 

$00fb0298 

+10 

Device 

scsidisk 

37.4 

(2/26/1) 

$00fd3f6c 

+10 

Library 

intuition 

37.220 

(3/14/91) 

$00f83ca4 

+5 

Special 

alerthook 

$00f8b358 

+5 

Device 

console 

37.85 

(3/13/91) 

$00fab5f4 

+0 

Library 

mathieeesingbas 

37.2 

(2/7/91) 

$00f86508 

-35 

Special 

syscheck 

37.2 

(1/15/91) 

$00fb7620 

-40 

Special 

romboot 

37.23 

(3/15/91) 

$00fff46c 

-45 

Special 

Magic 

36.7 

(3/16/90) 

$00f864c8 

-50 

Special 

bootmenu 

37.2 

(1/15/91) 

$00fb763a 

-60 

Special 

strap 

37.23 

(3/15/91) 

$00f98f3e 

-81 

Special 

fs 

37.11 

(3/13/91) 

$00fae70c 

-100 

Special 

ramlib 

37.13 

(3/14/91) 

$00f847f0 

-120 

Device 

audio 

37.7 

(3/13/91) 

$00f90390 

-120 

Library 

dos 

37.22 

(3/15/91) 

$00f9e4d0 

-120 

Library 

gadtools 

37.82 

(3/14/91) 

$00fa445c 

-120 

Library 

icon 

37.6 

(3/2/91) 

$00fab110 

-120 

Library 

mathffp 

37.1 

(1/13/91) 

$00fbba7a 

-120 

Task 

Pre-2.0  LoadWB  stub 

$00feccd4 

-120 

Library 

wb 

37.108 

(3/14/91) 

$00f88d8e 

-121 

Special 

con-handler 

37.39 

(3/13/91) 

$00fb2ed4 

-122 

Special 

shell 

37.37 

(3/13/91) 

$00fabbb8 

-123 

Special 

ram 

37.9 

(3/15/91) 

Some  modules  are  only  included  for  backward  compatibility.  For 
example,  the  workbench-task  module  and  the  "mathffp.library"  are  used. 
All  other  modules  contained  in  ROM  are  used  frequently  or  are  required 
by  other  modules. 
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Disk  Libraries  and  Devices 

Modules  are  found  in  ROM,  on  the  Workbench  disk  or  in  the  system 
directory  of  the  hard  drive.  These  programs  are  loaded  as  they  are  used: 


Name 

Version 

Directory 

asl. library 

37.25 

"LIBS" 

commodities.library 

37.5 

diskfontlibrary 

36.50 

iffparse.library 

37.1 

mathieeedoubbas.library 

37.1 

mathieeedoubtrans.library 

37.1 

mathieeesingtrans.library 

37.1 

mathtrans.library 

37.1 

translator.library 

37.1 

version.library 

37.33 

rexxsyslib.  library 

36.19 

rexxsupport.library 

34.9 

clipboard.device 

37.4 

"DEVS" 

narrator.device 

37.5 

parallel.device 

37.1 

printer.device 

35.603 

serial  .device 

37.1 

aux-handler 

"L" 

port-handler 

speak-handler 

queue-handler 
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1.2     AmigaOS  2.x  Compatibility 


The  addresses  of  routines  in  ROM  will  vary  from  version  to  version.  They 
should  not  be  called  directly,  since  they  are  always  subject  to  change.  In 
short,  do  not  rely  on  a  specific  value  for  anything  that  Commodore  has 
not  declared  a  constant.  A  disadvantage  with  compatibility  is  the 
memory  requirements  of  programs.  The  new  operating  system  uses  more 
memory  than  earlier  versions  to  accommodate  its  many  new  features.  The 
same  is  true  for  program  stack  requirements.  System  routines  have 
become  much  more  complex,  with  a  corresponding  increase  in  their  stack 
storage  needs. 

Many  values  whose  contents  are  made  up  of  flag  bits  have  been 
expanded,  and  failure  to  handle  them  accordingly  can  lead  to  problems. 
Also,  this  can  happen  to  the  68030's  expanded  status  register. 
Unfortunately,  some  system  data  not  defined  as  PUBLIC  has  found  its 
way  into  circulation.  These  values  are  not  to  be  trusted  and  changes  in 
their  definitions  can  most  likely  happen.  The  programmer  can  always  rely 
on  the  address  $00000004.  This  is  the  base  address  of  the  "exec  .library" 
for  all  versions  of  the  operating  system.  All  other  values  are  uncertain. 
The  color  and  proportions  of  the  system  font  can  also  change.  Processor 
speed  has  increased  dramatically.  As  a  rule,  a  program  will  have  to  be 
synchronized  with  clock  impulses  or  the  monitor's  electron  beam. 

The  main  and  co-processors'  instructions  doesn't  allow  interval  storage 
of  values,  bits  in  addresses  or  instruction  codes. 

Many  extensions  of  AmigaOS  1.3  have  been  removed  and  integrated 
into  the  base  module  in  a  large  expanded  form.  For  example,  the 
"romboot.library"  was  removed  and  the  boot  routine  completely 
reprogrammed.  Autobooting  from  devices  other  than  the  internal  disks  is 
now  standard  and  fully  supported  by  the  system.  Like  the  SCSI-devices, 
all  disks  come  bootable  from  the  supplier.  Drives  DF0  through  DF3  are 
assigned  priorities  of  +5,  -10,  -20,  and  -30. 

Early  in  the  reset-routine  the  new  operating  system's  enhancements 
become  apparent.  Calling  of  the  ColdCapture  vector  is  delayed.  At  any 
time  the  Exception/Interrupt  Table  can  be  placed  over  the  Vector  Base 
Register  (VBR). 
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1.2  AmigaOS  2jc  Compatibility 


There  are  allowances  for  changing  the  size  and  type  of  MemHeader 
structures,  and  the  use  of  ResetWindows  has  been  revised. 

The  base  structure  of  the  Expansion-library  is  declared  as  PRIVATE  and 
may  not  be  accessed.  Any  expansions  are  incorporated  in  two  passes 
accompanied  by  the  sorting  of  address  slots. 

The  "dos.library"  is  greatly  expanded  and,  like  many  other  modules, 
programmed  with  the  SAS  C-compiler  Version  5.  Its  base  structure  now 
conforms  to  that  of  the  other  libraries.  However,  for  compatibility 
reasons,  some  addresses  still  exist  as  BCPL-pointers.  New  types  of 
DosPackets  and  new  locks  have  been  implemented.  The  process 
structure  has  grown  substantially,  so  that  auto-creation,  for  example  with 
the  popular  "arp.library,"  results  in  a  system  crash. 

The  Workbench,  which  has  changed  in  appearance  and  color,  can  now 
be  nearly  any  desired  size,  shade  and  resolution.  Window  frames  and 
gadgets  adjust  automatically  to  changes  in  resolution  and  fonts. 
Workbench  windows  can  be  transferred  to  other  screens.  Screens,  which 
can  consist  of  up  to  16368*16384  pixels,  are  capable  of  new  display 
modes,  overscan  into  the  unseen  border  area,  and  several  styles  of 
horizontal  and  vertical  scrolling.  All  data  necessary  to  duplicate  a  screen 
can  no  longer  be  determined  from  the  screen  structure.  Screen  handling 
is  greatly  improved  and,  even  with  SimpleRefresh  windows,  a  message  is 
sent  only  when  refresh  is  necessary.  Different  color  borders  indicate 
which  windows  are  active  and  special  effects  create  a  3-dimensional 
appearance.  There  are  new  IDCMP-flags  for  this,  and  both  keyboard 
flags  now  transmit  raw  data  for  special  keys. 

The  Layer  system  is  improved.  SimpleRefresh  layers  are  saved  and 
refreshed  to  the  fullest  possible  extent.  The  routines  FattenLayerlnfo, 
ThinLayerlnfo,  and  InitLayers  should  no  longer  be  used;  NewLayerlnfo 
accomplishes  all  these  functions. 

Computing  of  Copper  lists  has  been  optimized.  The  video-hardware  does 
not  like  programming  errors,  such  as  switching  off  the  display  mode  in 
mid-display.  GetColorMapO  must  be  used  to  manipulate  ColorMap 
structures,  which  have  increased  in  size.  Row/cols  values  in  the  GfxBase 
no  longer  relate  to  the  Workbench. 
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1.  Kickstart  2.04 


Although  the  font  structures  have  a  new  format,  the  old  one  continues  to 
be  supported.  The  system-area  of  "font"  files  has  been  changed. 
Character  set  sizes  that  are  not  present  are  now  simply  calculated.  The 
topaz  font  is  still  in  ROM,  but  now  as  a  sans-serif  variant  for  increased 
legibility  at  high  resolutions.  Size  and  proportions  of  the  system  font  can 
be  specified  as  desired. 

Many  CLI/Shell  commands  are  stored  in  ROM,  and  several  CLI/Shell 
processes  can  run  simultaneously.  Windows  are  now  equipped  with 
close  gadgets  that,  when  activated,  cause  an  EOF  code  to  be  sent.  The 
missing  cursor  error  in  SuperBitmap  Console  windows  has  been 
corrected. 

The  Audio  device  no  longer  is  initialized  until  its  first  use,  which  can 
result  in  errors  because  of  insufficient  memory. 

Several  serial  interfaces  (expansion  cards)  are  possible.  However,  this  can 
lead  to  problems  with  the  adjustment  of  certain  parameters  through  the 
Serial  device. 

Trackdisk  device  buffers  can  be  released,  but  a  subsequent  attempt  to 
use  a  buffer  may  result  in  an  error  if  insufficient  memory  is  available. 

Both  CIAB  timers  are  now  accessible. 

The  current  maximum  for  chip  RAM  is  2  Meg.  Fast  RAM  is  configured 
down  from  the  upper  boundary  of  memory  (in  full  32  bit  addresses)  and 
can  be  as  high  as  8  Gigabytes.  This  configuration  will  make  it  easier  for  a 
future  release  to  break  the  2  Meg  chip  RAM  barrier,  probably  reaching 
as  high  as  8  Meg. 

The  ECS  has  more  hardware  registers,  which  reside  in  between  those 
familiar  to  the  previous  system  and  can  cause  problems  for  programmers 
of  clockcycle-optimized  programs.  Some  old  registers  contain  important 
new  bits.  The  accubuffered  truetime  clock  is  not  compatible  with  earlier 
clock  chips. 
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2.1   The  Workbench 


2.    Using  the  Amiga  3000 


We  recommend  working  through  the  following  exercises  step  by  step. 
While  providing  a  quick  overview  of  the  use  and  capabilities  of  the 
3000,  a  lot  of  important  information  is  included  that  everyone  will  find 
useful. 


2.1      The  Workbench 


Since  the  SCSI  hard  disk  comes  factory-installed,  a  few  seconds  after 
switching  on  the  computer  the  graphical  user  interface,  called  the 
Workbench,  appears.  If  you're  already  familiar  with  previous  versions  of 
the  Amiga,  you'll  immediately  notice  some  changes.  The  Workbench 
window  is  no  longer  just  a  background  screen.  It  has  acquired  a  border 
with  which  it  can  be  moved  around,  brought  into  the  foreground  or 
reduced  in  size.  There  is  even  a  close  gadget  (which  should  be  used 
carefully).  Professional  color  selection  and  the  appearance  of 
3-dimension  are  impressive  enhancements  that  dress  up  the  Workbench 
window. 

There  is  now  just  a  single  gadget  for  superimposing  windows:  the 
back/front  gadget.  Click  on  it  once  and  the  screen  or  window  is  brought 
into  the  foreground.  A  second  click  restores  the  object  to  the 
background.  Next  to  the  back/front  gadget,  a  window  has  a  new  gadget, 
by  which  it  can  be  toggled  between  two  alternate  sizes  and  positions. 
This  is  referred  to  as  the  alternate  gadget. 


2.1.1  Starting  AmigaOS  2.x 


At  this  point  some  suggestions  concerning  the  startup  of  the  Workbench 
may  be  helpful.  Let's  begin  with  the  Startup-sequence  script  file  in  the  S 
directory.  This  file  contains  all  the  commands  and  parameters  necessary 
to  start  the  system.  Configuring  the  system  to  one's  own  wishes  used  to 
require  making  various  changes.  Remember  if  a  command  results  in 
output  to  the  InitialCLI  window,  the  Workbench  screen  is  opened  and 
the  CLI  window  appears  on  it.  This  is  not  desired,  since  there  is  the 
opening  of  windows  on  the  Workbench  screen  before  the  screen  itself  is 
activated.  Here's  why. 
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When  the  LoadWB  command  wants  to  open  the  Workbench,  the 
"workbench.library"  attempts  to  use  the  stored  display  mode  for  the 
Workbench  screen.  If  the  screen  is  not  yet  present,  there  is  no  problem.  If 
it  is,  an  attempt  is  made  to  close  it  and  open  a  new  one  in  the  desired 
mode.  This  fails  when  the  screen  to  be  closed  contains  a  CLI  or  user 
window. 

The  result  is  a  system  requester  requesting  that  all  windows  be  closed. 
Let's  assume  a  user  is  working  with  the  A2024  monitor,  which  requires  a 
special  driver.  Suddenly  nothing  can  be  seen  on  the  screen,  and  without 
an  understanding  of  the  system,  nothing  can  be  done  to  solve  this 
problem. 

Several  things  could  be  done  to  prevent  this  situation  from  occurring. 
First  of  all,  only  those  commands  that  must  be  executed  before  the 
activation  of  the  Workbench  should  precede  the  LoadWB  command. 
Secondly,  the  "Command  >NIL:  parameter"  format  should  be  used  to  null 
their  output. 

Another  possibility  is  offered  through  the  directory  WbStartup.  All 
programs  (i.e.,  icons  that  are  located  here)  are  started  after  activation  of 
the  Workbench,  just  as  if  they  were  selected  with  a  double-click  of  the 
left  mouse  button.  For  example,  if  you  will  be  working  for  an  extended 
amount  of  time  with  a  particular  word  processing  task,  you  can  simply 
place  the  icon  of  the  word  processor,  or  the  text  itself,  in  this  directory. 
Startup-sequence  complications  with  autostarting  programs  can  be 
avoided  by  simply  modifying  the  placement  of  icons. 


2.1.2  The  Workbench  Menus 


Your  acquaintance  with  the  Amiga  will  require  you  to  be  familiar  with 
the  Workbench  menu  functions.  Even  CLI  enthusiasts  should  make 
thorough  use  of  them,  since  now  the  CLI  can  be  entirely  replaced  by  the 
graphical  user  interface.  Before  we  proceed  with  the  individual  items,  we 
should  mention  one  more  innovation  regarding  the  selection  of  icons.  If 
you  press  the  left  mouse  button  and  hold  it  down  while  moving  the 
mouse,  a  rectangular  box  appears  on  the  Workbench  or  in  a  Workbench 
window.  When  the  left  mouse  button  is  released,  all  the  icons  within  the 
box  are  selected,  a  better  procedure  than  multiple  selections  using  the 
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The  "Workbench"  menu  contains  items  that  are  independent  of  file  or 
directory  selections: 

Backdrop  This  item  is  used  to  manipulate  the  Workbench  window. 

Selecting  it  removes  the  border,  enlarges  the  window  to 
the  full  screen  size  and  places  it  behind  all  other 
windows.  The  former  condition  is  restored  when  the 
item  is  selected  again. 

Execute  Command 

Causes  a  CLI/Shell  command  to  be  executed.  A 
requester  appears  in  which  a  command  can  be  entered 
the  same  as  in  the  Shell.  A  new  window  is  opened  for 
resulting  output  and  can  again  be  closed  with  the  use  of 
a  close  gadget. 

Redraw  All  If  programs  have  cluttered  or  disrupted  the  workbench 
screen,  you  can  use  this  item  to  restore  all  windows  and 
icons  to  their  original  condition. 

Update  All  If  you  are  working  with  the  Workbench  and  the  Shell, 

you  can  use  this  item  to  show  changes  you  have  made 
to  directories  with  the  Shell.  It  updates  Workbench 
memory  and  redraws  the  screen  to  reflect  the  current 
status. 


Last  Message 


About 


Quit 


The  last  message  to  appear  on  the  title  bar  is 
redisplayed. 

Displays  a  requester  showing  the  version  numbers  of 
the  operating  system  and  Workbench  you  are  using. 
This  also  shows  the  copyright  notice. 

This  is  the  same  as  clicking  on  the  close  gadget  of  the 
Workbench.  If  the  Workbench  is  not  blocked  by  any 
program  windows,  you  can  close  it  after  confirming 
your  decision  in  a  requester.  This  frees  up  memory  for 
processes  such  as  graphics  programs  that  may  have 
large  memory  requirements. 
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The  "Window"  menu  contains  items  that  refer  to  directories  and  drives. 
They  affect  only  the  active  window: 

New  Drawer  Makes  a  new  directory  and  provides  an  icon  for  it.  The 
name  of  the  directory  can  be  entered  in  a  requester. 

Open  Parent  When  one  directory  is  located  within  another  directory, 
which  in  turn  is  located  within  a  third,  it  may  be 
advisable  to  close  the  respective  parent  directories. 
Selecting  this  item  will  again  open  the  directory  in 
which  the  current  window's  directory  is  located. 

Close  Closes  the  current  window  (directory). 

Update  In  earlier  versions,  directory  changes  that  were  not 

applied  to  the  Workbench  had  to  be  remade  with  each 
close  and  subsequent  reopen  of  the  directory  in  order  to 
be  reflected  on  the  screen.  This  item  provides  a  simple 
way  of  keeping  a  window's  information  current. 

Select  Contents  If  you  want  to  work  with  all  entries  of  a  directory,  the 
entire  contents  can  be  selected  with  this  item. 

Clean  Up  Tidies  up  a  window  by  reorganizing  its  icons  according 

to  the  window's  size. 

Snapshot  Stores  the  size  and  position  of  the  current  window 

(submenu  item  "Window")  and  the  order  of  all  the  icons 
it  contains  (submenu  item  "All"). 

Show  Determines  what  will  be  shown  in  the  current  window. 

The  submenu  item  "Only  Icons"  is  the  default.  This 
shows  only  those  objects  that  have  an  icon  file  (".info" 
file).  All  other  entries  are  also  shown  when  you  select 
the  "All  Files"  submenu  item.  For  example,  this  enables 
you  to  display  CLI  commands  and  double-click  to  start 
them,  whereby  a  requester  appears  permitting  the  input 
of  parameters. 

View  By  The  preset  submenu  item  "Icon"  shows  the  directory 

contents    by    icons    and,    underneath    them,    the 
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corresponding  filenames.  All  other  options  produce  a 
scrollable  list  of  entries  without  icons.  The  entries  that 
appear  in  this  list  are  determined  by  the  "Show"  criteria. 
Their  sequence  is  determined  by  the  three  remaining 
"View  By"  submenu  items.  Entries  can  be  sorted  by 
"Name"  of  file,  by  "Size",  or  by  "Date"  created.  Files  can 
be  selected  from  these  lists  as  they  can  from  the  display 
of  icons. 

The  "Icon"  menu  contains  functions  relating  to  icons.  The  upper  portion 
consists  of  general  activities  and  the  lower  portion  consists  of  special 
icons  only. 

Open  Opens  the  selected  icon,  which  is  the  same  as  double- 

clicking  on  the  icon  with  the  mouse. 

Copy  Makes  a  copy  of  a  file,  directory  or  diskette. 

Rename  Changes  the  name  of  an  object. 

Information         Opens  a  large  requester  in  which  all  data  about  an  icon 
can  be  displayed  and  manipulated. 

Snapshot  Saves  the  position  of  the  selected  icon. 

Unsnapshot        Deletes   position    information    of   icons    saved   in 
"Snapshot". 

Leave  Out  One  of  the  most  convenient  features  of  the  new 

Workbench.  Selected  icons  are  saved  in  the  main 
Workbench  window.  This  makes  it  possible  to  select  the 
icon  again  without  reopening  its  directory.  The  Leave 
Out  configuration  is  saved  and  remains  in  effect  even 
after  resetting  or  turning  off  the  computer. 

Put  Away  Removes  icons  placed  in  the  Workbench  window  by 

Leave  Out  and  displays  them  again  with  their  respective 
directories. 


Delete 


Deletes  all  selected  icons  and  their  files  or  directories 
after  confirmation  using  a  requester. 
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Format  Disk        Formats  a  diskette.  The  disk  is  initialized  and  given  the 
name  "Empty".  The  diskette  icon  is  then  displayed. 

Empty  Trash       Deletes  the  contents  of  the  Trashcan  directory. 

The  "Tools"  menu  normally  contains  only  the  "ResetWB"  function, 
which  returns  the  entire  Workbench  to  its  initial  status.  This  menu  was 
intended  for  user-defined  items.  Unfortunately,  no  utility  for 
incorporating  programs  into  menus  is  supplied,  although  the  public- 
domain  "ToolManager"  (Fish  476)  can  be  used  to  accomplish  this. 

2.1.3  The  Workbench  Programs 

Now  let's  look  at  the  programs  that  Workbench  Version  37  Revision  64 
contains.  We  begin  with  the  "Prefs"  directory,  since  you  will  find  all  the 
programs  needed  to  tailor  the  system  to  your  needs: 

Input  This  program  establishes  all  the  time  constants  for 

interrogating  the  keyboard  and  the  mouse.  With  the 
"Mouse  Speed"  slider,  you  control  how  much  the  mouse 
must  be  moved  to  cause  a  corresponding  movement  of 
the  mouse  pointer.  A  low  value  indicates  that  a  small 
movement  of  the  mouse  will  change  the  position  of  the 
pointer.  If  this  is  not  adequate,  you  can  click  on  the 
"Acceleration"  box.  A  check  mark  appears  in  the  box 
when  Acceleration  is  selected.  Now  the  slightest 
movement  of  the  mouse  will  cause  a  large  displacement 
of  the  pointer.  You  may  have  to  go  back  and  adjust  the 
Mouse  Speed  after  selecting  Acceleration. 

The  "Double-Click"  slider  sets  the  maximum  time  span 
that  can  separate  two  clicks  before  they  will  be 
recognized  separately  rather  than  as  a  double-click. 
You  can  try  this  out  with  the  "Test"  button.  If  a  double- 
click is  recognized,  this  is  indicated  in  the  "Show"  box. 

"Key  Repeat  Delay"  sets  the  time  after  which  a  key  that 
is  struck  and  not  released  will  be  considered  struck 
again. 
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"Key  Repeat  Rate"  is  the  speed  at  which  a  letter  will 
appear  on  the  screen  as  repeated  input  once  the  Key 
Repeat  Delay  is  reached  and  the  key  continues  to  be 
held  down.  This  can  be  checked  in  the  Key  Repeat  Test 
field. 

IControl  IControl  establishes  keyboard  commands  that  take  the 

place  of  complicated  mouse  operations.  "Verify 
Timeout"  is  the  timespan  that  keys  must  be  pressed  to 
activate  the  corresponding  action.  "Command  Keys"  are 
letter  keys  that  are  pressed  in  combination  with  the  left 
<Amiga>  key  to  perform  certain  actions.  For  example,  to 
move  the  Workbench  into  the  foreground  and  the  front 
screen  into  the  background,  or  to  substitute  for  the 
"OK"  and  "Cancel"  gadgets  of  some  system  requesters. 
IControl  allows  you  to  specify  the  letters  to  be  used  for 
these  actions. 


"Mouse  Screen  Drag"  keys  are  used  with  the  mouse  to 
drag  the  screen  both  horizontally  and  vertically.  With 
IControl  you  can  specify  the  keys  (I  Shift  |.  fctril  ,(AJt) 
and/or  <Amiga>)  that  must  be  held  down  along  with  the 
left  mouse  button  for  this  operation.  When  such  keys 
are  paired  on  the  keyboard,  the  left  one  should  be  used. 


"Avoid  flicker"  provides  for  flicker-free  text  in  special 
display  modes.  "Preserve  colors"  ensures  stability  and 
fidelity  of  color.  With  "Screen  menu  snap",  menus  will 
always  be  shown  in  the  visible  area  of  the  screen,  and 
with  "Text  gadget  filter",  control  characters  are  filtered 
out  of  text. 


Palette 


This  allows  the  colors  of  the  Workbench  to  be  changed. 
The  currently  selected  color  appears  in  a  box  to  the  left 
of  the  palette.  Below  it  the  red,  green  and  blue  intensity 
of  the  selected  color  can  be  adjusted. 


WBpattern  The  main  Workbench   window   and   its   directory 

windows  are  displayed  with  a  background  pattern.  The 
editor  WBpattern  lets  you  choose  these  patterns  from 
eight  preset  selections. 
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Font 


Pointer 


ScreenMode 


OverScan 


Allows  selection  of  the  character  sets  to  be  used  for  the 
text  underneath  icons,  for  that  displayed  in  the  title  bars 
of  screens  and  windows,  and  for  the  default  text  of  the 
system.  You  can  also  specify  whether  or  not  the 
background  field  behind  text  characters  should  be 
colored.  Color  selections  for  text  and  field  are  made 
separately. 

With  this  preference  you  can  change  the  appearance  of 
the  mouse  pointer  and  adjust  the  "hot  spot"  (i.e.,  the 
portion  of  the  pointer  capable  of  activating  an  object). 

Here  the  resolution  and  display  mode  of  the  Workbench 
is  established.  The  Workbench  can  be  made  larger  than 
the  visible  area  of  the  screen.  You  can  specify  whether 
or  not  the  screen  display  should  "Autoscroll"  when  the 
selected  "Width"  and  "Height"  values  exceed  the  visible 
screen  dimensions.  The  number  of  possible  colors  can 
also  be  determined  according  to  screen  mode. 

If  you  have  a  monitor  on  which  the  border  area  around 
the  Workbench  is  visible,  then  you  can  also  enlarge  the 
Workbench.  With  "Edit  Text  Overscan"  and  "Edit 
Standard  Overscan"  you  can  inform  the  system  of  the 
normal  visible  area  of  your  monitor  and  the  desired 
overscan  display  size.  A  program  can  then  open  a 
screen  that  extends  beyond  the  normal  text  area,  so  that 
no  border  is  visible. 


Printer 


PrinterGfx 


This  program  allows  you  to  tell  the  system  what  type  of 
printer  is  connected  to  your  computer,  through  which 
port  it  is  connected,  what  kind  of  paper  you  are  using, 
and  various  preferences  regarding  text  output. 

Here  you  can  define  several  specifications  for  the 
output  of  graphics  to  the  printer.  Next  to  the  "Color 
Correct"  area,  you  can  choose  the  "Smoothing"  option 
to  round  sharp  edges  and  offset  or  centering  options. 
Other  specifications  include  "Dithering,"  "Scaling," 
"Image,"  "Aspect"  and  "Shade". 
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Serial  This  program  sets  the  data  transfer  parameters  for  a 

modem  connected  to  the  serial  port.  The  maximum  rate 
supported  is  31250  baud. 

Time  This  program  establishes  the  date  and  time  and  sets  the 

accubuffered  truetime  clock  accordingly. 

The  "System"  directory  contains  programs  that  are  used  primarily  by  the 
operating  system.  The  exceptions  to  this  rule  are  "SetMap,"  by  which 
you  can  change  the  assigned  keyboard  layout,  "NoFastMem,"  which 
disables  the  Fast  RAM  area,  and  "FixFonts,"  which  should  always  be  run 
following  changes  in  the  Fonts  directory. 

In  the  "Utilities"  directory  there  are  a  few  small  programs  that  perform 
helpful  tasks: 

Clock  Displays  the  time  in  analog  or  digital  format  and  has  an 

alarm  function. 

More  This  is  a  program  for  reading  text  files.  You  can  scan 

through  the  text  within  a  window  one  page  or  line  at  a 
time. 

Display  Graphics  in  IFF  format  and  even  slideshows  can  be 

displayed  with  this  program. 

Say  A  simple  program  to  convert  typed  text  into  computer- 

synthesized  speech. 

Exchange  and  Commodities 

This  is  the  main  program  of  an  assortment  of  small 
utilities.  It  controls  the  following  programs:  "Autopoint" 
automatically  activates  the  window  over  which  the 
mouse  pointer  is  located,  "Blanker"  blanks  out  the 
screen  when  no  input  has  been  received  for  a  specified 
period  of  time,  "FKey"  assigns  function  keys,  "IHelp" 
allows  keyboard  commands  to  replace  many  mouse 
operations,  and  "NoCapsLock"  forces  software 
disabling  of  the  leaps  Lock  \  key. 
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2.2     The  Command  Line  Interpreter 

The  Shell  is  a  window  in  which  you  can  enter  command  lines  to  control 
the  Amiga.  A  command  line  consists  of  a  program  name  and,  in  some 
cases,  additional  parameters. 


2.2.1 


AmigaOS  2.x  Resident  Commands 

Unlike  in  previous  versions  of  the  Amiga  operating  system,  under 
AmigaOS  2.x  many  programs  are  stored  in  ROM.  This  allows  faster 
processing  and  trouble-free  manipulation  of  system  directories.  Some 
programs  stored  in  ROM  are  also  kept  in  the  current  system  directory, 
because  programs  written  for  earlier  versions  expect  them  there  and 
require  them  for  execution. 

The  following  commands  are  implemented  in  ROM: 


2.2.2 


Alias 

Get 

Set 

Ask 

Getenv 

Setenv 

CD 

If 

Skip 

Echo 

Lab 

Stack 

Else 

NewCLI 

Unalias 

EndCLI 

NewShell 

Unset 

Endlf 

Path 

Unsetenv 

EndShell 

Prompt 

Why 

EndSkip 

Quit 

.bra 

Failat 

Resident 

.ket 

Fault 

Run 

.key 

Using  the  CLI 


The  Shell  or  CLI  provides  many  features  to  help  you  edit  the  current 
command  line: 

The  left  and  right  cursor  control  keys  move  the  cursor  one  character 
position  in  the  indicated  direction.  When  used  in  conjunction  with  the 
lst1i"l  key,  they  move  the  cursor  to  the  beginning  or  end  of  the  line 
respectively. 
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The  I  Backspace  \  key  erases  the  character  to  the  left  of  the  cursor.  The  fDefl 
key  erases  the  character  at  the  cursor  position. 

[Ctrl  l+fm  This  corresponds  to  I  Backspace).  [ctrH+fM>  to  [Enter! ,  and 

(ctrQ+Q}  to  Help. 

[ctn  |+fw)  This  erases  the  previous  word. 


[ctril+fT)  This   erases   the   entire   window    (works    only   in 

combination  with  (Enter)). 

( ctn  >+Txl  This  erases  the  entire  command  line. 


Ictrit+Jui  This  erases  the  line  from  the  beginning  up  to  the  cursor 

position. 

[Ctrl  I+TkI  This  erases  the  line  from  the  cursor  position  to  the  end. 

This  aborts  an  executing  program,  command  file,  etc. 

Previously  entered  commands  are  stored.  You  can  scan  up  or  down 
through  this  list  with  the  cursor  control  keys.  There  is  a  search  function 
for  quickly  locating  a  particular  command  within  a  list.  Simply  type  the 
first  few  characters  of  the  command  you  wish  to  locate.  Then  press  the 
up  or  down  cursor  control  key  together  with  the  I  Shin)  key  to  begin 
searching  in  the  desired  direction  for  the  first  line  that  begins  with  the 
typed  sequence. 

In  the  Shell  window,  blocks  of  text  can  be  marked  with  the  mouse  and 
with  <rt-Amiga>  +  (c)  as  in  a  word  processor.  The  block  can  be  copied  to 
another  window  by  pressing  <rt-Amiga>+(v)  after  activating  the 
window  that  is  to  receive  the  text. 

If  you  enter  a  command  in  a  Shell  window  that  is  too  small  to  hold  the 
entire  output,  the  initial  lines  will  scroll  off  the  top  of  the  window  and 
disappear  from  view.  Enlarging  the  window  will  cause  them  to  reappear. 
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3.     Programming  with  AmigaOS  2.x 

The  basic  concept  of  the  operating  system  has  been  changed 
considerably  from  the  old  1.x  versions.  In  just  about  every  area,  the 
programmer  is  given  opportunities  to  query,  influence,  or  completely 
determine  system  processes.  The  operating  system  has  become  much 
more  open,  and  offers  good  potential  for  multi-user  systems.  Many 
system  routines  were  re-programmed  with  new  capabilities.  In  order  to 
maintain  compatibility  with  old  software,  many  of  the  calling 
conventions  from  the  1.x  versions  were  implemented,  and  sometimes  the 
function  results  were  partially  modified.  New  libraries,  resources,  and 
devices  were  added.  The  familiar  system  modules  were  expanded  to  the 
point  that  they  can  hardly  be  recognized  anymore.  All  in  all,  AmigaOS 
2.x  is  a  completely  new  operating  system  that  is  compatible  with  the  old 
versions. 

Normal  versions  of  AmigaOS  2.x  can  only  work  on  a  machine  that  has 
the  same  hardware  configuration  as  the  Amiga  3000  (68030,  FPU, 
Commodore  clock  chip,  HR  chip  set,  etc.).  This  is  because  the  reset 
routine  starts  out  with  68030  commands  without  even  querying  the  CPU 
type.  Some  test  versions  can  also  be  installed  on  the  16  bit  machines,  but 
there  is  a  lot  less  room  in  the  512K  ROM,  so  many  features  are  only 
partially  functional  or  are  missing  altogether. 

3.1      The  Libraries  and  their  Functions 

A  lot  of  information  is  required  to  produce  a  good  program.  All  the  data 
on  AmigaOS  2.x  would  fill  thousands  of  pages  and  extend  far  beyond 
what  we  could  hope  to  effectively  cover  in  this  book.  Therefore,  we  had 
to  limit  ourselves  to  a  selected  portion.  We  chose  to  focus  on  the  library 
functions  in  this  book.  Library  routines  provide  the  building  blocks  and 
hand  tools  for  creating  more  complex  application  programs,  such  as  a 
word  processor.  Because  there  are  so  many  functions  to  cover,  we  also 
chose  to  do  without  an  introductory  overview  for  beginners.  For 
example,  there  are  many  other  good  books  with  this  kind  of  information, 
such  as  "The  Amiga  System  Programmers  Guide". 

A  brief  glance  at  the  system  routines  will  reveal  the  existence  of  two  new 
structures  =  Tagltem  fields  and  Hooks.  Tagltem  fields  are  variable  in  size 
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and  structure.  They  are  primarily  used  to  pass  parameters.  A  Tag  field  can 
belong  to  several  memory  blocks.  It  consists  of  several  Tagltems.  A 
Tagltem  consists  of  two  32  bit  values  (Longs).  The  first  value  is  a  code 
for  interpreting  the  meaning  of  the  second  value,  which  is  the  data  Long. 
Depending  on  the  code,  the  data  can  be  an  address,  a  BCPL  pointer, 
Words,  Bytes,  Flags,  or  combinations  thereof.  Tagltems  are  most  often 
used  to  change  system  routine  default  settings.  This  could  be  for  a  small 
change,  such  as  setting  the  ECS  presentation  mode  for  a  new  screen,  or 
for  changes  to  the  basic  system  configuration  that  require  large  numbers 
of  parameters.  Tagltem  fields  are  required  in  order  to  use  certain  OS-2.04 
features. 

Another  important  new  structure  is  the  Hook.  Hooks  give  the 
programmer  deep  access  into  the  system.  In  general,  Hooks  are  structures 
with  addresses  to  routines  of  their  own.  These  private  routines  are 
associated  with  certain  events  or  results.  When  a  certain  event  or  result  is 
encountered,  the  system  jumps  to  the  corresponding  routine.  Hooks  can 
be  used  to  expand  upon  or  entirely  replace  system  functions. 

And  now,  the  description  of  each  library  in  alphabetical  order. 

3.1.1  The  ASL  Library 

The  ASL  library  provides  the  easiest  way  for  a  programmer  to  create  file 
requester  boxes.  Special  functions  can  be  applied  to  customize  each 
requester  box. 

This  library  is  found  under  the  name  "asl.library".  All  functions  of  this 
library,  expect  the  base  address  _AslBase,  is  a  parameter  in  the  A6 
register. 

Functions  of  the  ASL  Library 

1.  Standard  File  Requester  Box  2.  Complex  File  Requester  Boxes 

AllocFileRequest  AllocAslRequest 

FreeFileRequest  FreeAslRequest 

RequestFile  AslRequest 
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Description  of  Functions 

1.  Standard  File  Requester  Box 

[AllocFileRequest  Get  FileRequester  structure  | 

Call:  request  =  AllocFileRequest  ( ) 

DO  -30 (a6) 

STRUCT  FileRequester   *request; 

Function:  Obtains  and  initializes  all  data  structures  required  for  a 
RequestFile()  function  call. 

Arguments:  None.  The  initialization  is  automatically  executed  for  the 
standard  file  requester.  If  you  want  to  use  special  functions, 
you  must  obtain  the  data  structures  with 
AllocAslRequest(). 

Result:  Address  of  a  FileRequester  structure  which  is  passed  to  the 

RequestFile()  function.  You  can  read  any  data  from  the 
normally  accessible  parts  of  the  FileRequester  structure.  In 
the  case  of  a  system  error,  such  as  no  memory,  the  value  0  is 
returned. 

Warning:  FileRequester  structures  passed  to  RequestFile()  or 
AslRequest  must  be  obtained  either  with 
AllocFileRequest()  or  AllocAslRequest().  Reserving 
memory  yourself  or  directly  manipulating  the  entries  in  the 
structure  will  crash  the  system. 

See  also:  RequestFile(),  FreeFileRequest(),  FreeAslRequest(), 
AslRequest() 

[FreeFileRequest  Free  file  requesterl 

Call:  FreeFileRequest  (   request    ) 

-36 (a6)  A0 

STRUCT  FileRequester  *request; 
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Function:      This  function  is  identical  to  Free  AslRequest().  It's  used  to 
free  a  data  structure  allocated  with  AllocFileRequest. 

Arguments:   request       Address  of  a  FileRequester  structure  that  was 

obtained  with  AllocFileRequest(). 

Result:  None. 

See  also:       FreeAslRequest() 

[RequestFile  Display  file  requester  and  evaluate  user  input  | 

Call:  result  =  RequestFile  (   request   ) 

DO  -42 (a6)  AO 

BOOL        result ; 

STRUCT  FileRequester  *request; 

Function:      A  file  requester  box  is  displayed,  the  user's  input  is 
processed,  and  the  requested  file  is  returned. 

Arguments:   request       FileRequester  structure  with  address  obtained 

via  AllocFileRequest(). 

Result:  result  0  means  Cancel  was  selected  or  a  system  error 

occurred.  The  exact  input  data  can  be  read 
from  the  FileRequester  structure. 

See  also:       AllocFileRequest(),  FreeFileRequest(),  AslRequest() 

2.  Complex  Requester  Boxes 

[Alloc Asl Request  Obtain  structures  for  a  requester  box| 

Call:  request  =  AllocAslRequest  (   type,   ptags   ) 

DO  -48 (a6)  DO  AO 

APTR  request; 

ulong        type; 

STRUCT  Tagltem     *ptags; 
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Function:      Obtains  and  initializes  the  data  structures  for  a  requester 

box. 

Arguments:   type  Type  of  requester  box,  ASL_FileRequest  for  a 

file  requester  or  ASL"FontRequest  for  a  font 
requester.  The  type  of  requester  box  is 
determined  by  AllocAslRequest  function  on 
the  basis  of  the  following  values: 

ASL_FileRequest  =  0 
ASL_FontRequest  =  1 

ptags  Address  of  a  Tagltem  field  used  to  pass  special 

functions  and  parameters. 

Result:  Address  of  an  initialized  data  structure  (FileRequester  or 

FontRequester).  A  value  of  0  is  returned  in  case  of  an  error. 
The  address  of  the  data  structure  is  passed  to  the  function 
AslRequest()  and  freed  with  FreeAslRequest(). 

See  also:       AslRequest(),  FreeAslRequest() 

|FreeAslRequest  Free  requester  box  data  structures! 

Call:  FreeAslRequest  (   request    ) 

-54 (a6)  AO 

APTR   request; 

Function:  Frees  the  memory  occupied  by  a  FileRequester  or 
FontRequester  structure.  The  address  must  have  been 
previously  obtained  with  AllocAslRequest()  or 
AllocFileRequest(). 

Arguments:   request       Address   of  a  data  structure  obtained   via 

AllocAslRequestO  or  AllocFileRequest(). 

Result:  None. 

See  also:       AllocAslRequestO,  AslRequestQ,  AllocFileRequest() 
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[AslRequest 


Display  and  query  requester  box| 


Call:  result   =  AslRequest  (   request,    ptags    ) 

DO  -60 (a6)  AO  Al 

BOOL        result; 

APTR   request; 

STRUCT  Tagltem  *ptags; 

Function:  Displays  a  requester  box  and  evaluates  the  input  of  the 
user.  The  type  of  box,  special  functions,  and  results  are 
dependent  upon  the  data  structure  and  definitions  passed 
to  the  Tagltem  field. 


Tag  Items 

ASLJHail  (STRPTR) 

Title  text  of  the  requester. 

ASL  Window  (struct  Window  *; 

Window  in  which  the  requester  will  appear. 

ASL  LeftEdge  (WORD) 

Left  edge  of  the  query  window. 

ASL  TopEdge  (WORD) 

Top  edge  of  the  query  window. 

ASL  Width  (WORD) 

Width  of  the  query  window. 

ASL  Height  (WORD) 

Height  of  the  query  window. 

ASL  HookFunc  (APTR) 

Address  of  an  implemented  function. 

ASL  File  (STRPTR) 

Default  filename  of  a  FileRequester. 

ASL  Dir  (STRPTR) 

Default  path  of  a  FileRequester. 

ASL  FontName  (STRPTR) 

Default  font  name  of  a  FontRequester. 

ASL  FontHeight  (UWORD) 

Default  font  height. 

ASL  FontStyles  (UBYTE) 

Default  font  style. 

ASL  FontFlags  (UBYTE) 

Special  flags  for  a  FontRequester. 

ASL  FrontPen  (BYTE) 

Foreground  color  of  a  FontRequester. 

ASL  BackPen  (BYTE) 

Background  color  of  a  FontRequester. 

ASL  MinHeight  (UWORD) 

Minimum  height  of  font. 

ASL  MaxHeight  (UWORD) 

Maximum  height  of  font. 

ASL  OKText  (STRPTR) 

New  text  for  the  OK  button  (up  to  6  char.). 

ASL  CancelText  (STRPTR) 

Same  for  the  CANCEL  button. 

ASL  FuncFlags  (ULONG) 

Function  Flags  for  the  requester. 

ASL  ExtFlagsl  (ULONG) 

Additional  Flags. 

Arguments:   request 


ptags 


Data  structure  obtained  with  AllocAslRequest() 
or  AllocFileRequest(). 

Address  of  a  Tagltem  field  containing  changes 
to  the  default  values. 


Warning:      The  only  valid  way  to  change  the  data  structure  entries  is 
with  Tagltems. 
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Result:  A  result  of  0  indicates  CANCEL  was  pressed  or  a  system 

error  occurred.  The  exact  user  input  can  be  taken  from  the 
readable  parts  of  the  data  structure. 

See  also:       Alloc AslRequest(),  FreeAslRequest() 

Data  Structures  And  Values: 


Dec  Hex 


STRUCTURE  FileRequestr,  0 


0  $00 

CPTR 

rf_Reservedl 

4  $04 

CPTR 

rf_File 

;  *filename  (PCHARS+1) 

8  $08 

CPTR 

rf_Dir 

;  *directory  (DSIZE+1) 

12  $0C 

CPTR 

r  f  _Re  s  e  r  ved2 

16  $10 

UBYTE 

rf_Reserved3 

17  $11 

UBYTE 

rf_Reserved4 

18  $12 

APTR 

rf_Reserved5 

22  $16 

WORD 

rf_LeftEdge 

24  $18 

WORD 

rf_TopEdge 

26  $1A 

WORD 

rf_Width 

28  $1C 

WORD 

rf_Height 

30  $1E 

WORD 

rf_Reserved6 

32  $20 

LONG 

rf_NumArgs 

36  $24 

APTR 

rf_ArgList 

40  $28 

APTR 

rf_UserData 

44  $2C 

APTR 

rf_Reserved7 

48  $30 

APTR 

rf_Reserved8 

52  $34 

CPTR 

rf_Pad 

Interactive  functions  associated  with  a  requester  must  look  like  this: 


rf_Function(  Mask,  Object  , AslRequester) 

4(A7)  8(A7)      12 (A7) 
ULONG        Mask; 
CPTR  *Object; 

CPTR  *Request; 


The  value  of  Mask  is  determined  by  passing  a  copy  of 
ASL_FunctionFlags,  which  is  generated  for  every  requester.  Object 
contains  the  address  of  data.  The  following  bits  (or  Flags)  are  defined  for 
a  FileRequester: 


RFB_DOWILDFUNC  =   7  ;call  with  AnchorPath  and  a  name, 
RFF_DOWILDFUNC   =  $80  ; (FileRequester) 
RFB_DOMSGFUNC   =   6  ; transmit  all  IDCMP  events 
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RFF_DOMSGFUNC  =  $40 
RFB_DOCOLOR  =  5 
RFF_DOCOLOR  =  $20 
RFB_NEWIDCMP  =  4 
RFF_NEWIDCMP  =  $10 
RFB_MULTISELECT  =  3 
RFF_MULTISELECT  =  $8 
RFB_PATGAD  =  0 
RFF_PATGAD       =   $1 


;that  are  not  for  the  FileRequester 
;bit  for  SAVE  operations 

;use  own  IDCMP  port 

,-notify  of  multiple  selection 

; query  a  Pattern  gadget 


Dec  Hex 


STRUCTURE  FontRequester , 0 


0  $00  CPTR  fo_Reservedl 

4  $04  CPTR  fo_Reserved2 

8  $08  APTR  fo_Name 

12  $0C  USHORT  fo_YSize 

14  $0E  UBYTE  fo_Style 

15  $0F  UBYTE  fo_Flags 

16  $10  UBYTE  fo_FrontPen 

17  $11  UBYTE  fo_BackPen 

18  $12  UBYTE  fo_DrawMode 

19  $13  UBYTE  fo_Reserved3 

20  $14  APTR  fo_UserData 
24  $18  SHORT  fo_LeftEdge 
26  $1A  SHORT  fo_TopEdge 
28  $1C  SHORT  fo_Width 

30  $1E  SHORT  fo_Height 


; result  string 


FONB_FrontColor 

= 

0 

FONF_FrontCo lor 

= 

$1 

FONB_BackColor 

= 

1 

FONF_BackColor 

= 

$2 

FONB_Styles 

= 

2 

FONF_Styles 

= 

$4 

FONB_DrawMode 

= 

3 

FONF_DrawMode 

= 

$8 

FONB_FixedWidth 

= 

4 

FONF_FixedWidth 

= 

$10 

FONB_NewIDCMP 

= 

5 

FONF_NewIDCMP 

= 

$20 

FONB_DoMs  gFunc 

= 

6 

FONF_DoMsgFunc 

= 

$40 

FONB_DoWildFunc 

= 

7 

F0NF_DoWi ldFunc 

= 

$80 

ASL_FuncFlags  for  FontRequester: 

query  foreground  color 

query  background  color 

query  font  style 

query  draw  mode 

allow  only  fixed  width  fonts 

use  own  IDCM  port 

capture  only  events  for  the  requester 

call  with  every  TextAttr  structure 
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Values  for  the  Tagltem  field  used  with  AslRequest(): 


ASL_Duirany 

= 

TAG_USER+$80000 

ASL_Hail 

= 

ASL_Dummy+l 

ASL_Window 

= 

ASL_Dumnty+  2 

ASL_LeftEdge 

= 

ASL_Dummy+3 

ASL_TopEdge 

= 

ASL_Dummy+4 

ASL_Width 

= 

ASL_Dummy+5 

ASL_Height 

= 

ASL_Dumrny+6 

ASL_HookFunc 

= 

ASL_Dummy+7 

ASL_File 

= 

ASL_Dummy+8 

ASL_Dir 

= 

ASL_Dummy+9 

ASL_Pattem 

= 

ASL_Dummy+10  ;FileRequester 

only 

ASL_FontName 

= 

ASL_Dummy+ 1 0  ; FontRequester 

only 

ASL_FontHeight 

= 

ASL_Dummy + 1 1 

ASL_FontStyles 

= 

ASL_Dummy + 1 2 

ASL_FontFlags 

= 

ASL_Dummy + 1 3 

ASL_FontPen 

= 

ASL_Dummy + 1 4 

ASL_BackPen 

= 

ASL_Dummy + 1 5 

ASL_MinHeight 

= 

ASL_Dummy + 1 6 

ASLJMaxHeight 

= 

ASL_Dummy+ 17 

ASL_OKText 

= 

ASL_Dummy+18 

ASL_CancelText 

= 

ASL_Dummy+19 

ASL_FuncFlags 

= 

ASL_Dummy+20 

ASL_ModeList 

= 

ASL_Dummy+21 

Example 

Let's  take  a  look  at  the  creation  of  a  simple  FileRequester  and  how  to 
query  its  result.  It's  rather  curious  that  a  simple  routine  like  this  does  not 
already  exist  as  a  function: 


** 

File  selection 

** 

Input : 

A6=_AslBase 

** 

A0=Buffer  (FCHARS+DSIZE+1) 

** 

Output : 

D0=Buffer  r  NULL 

** 

A6=_AslBase 

** 

A0=Buffer 

** 
** 
** 


_File  selection 
clr.b   (aO) 
movem.l  d0/a0,-(a7) 
jsr     _LVOAllocFileRequest(a6) 
move.l  dO, (a7) 


;0  bytes  in  buffer 
; result+buf f er 
;get  FileRequestr 
;save  result 
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beq.  s 

. Error 

;on  error  -> 

movea . 1 

dO,aO 

;move  FileRequestr  to  aO 

jsr 

_LV0RequestFile(a6) 

; display 

movem . 1 

(a7),a0-al 

,-FileRequestr+buf  fer 

move . 1 

aO.dl 

;save  FileRequestr 

move . 1 

dO, (a7) 

;test  Okay/Cancel 

beq.s 

.Cancel 

,-on  error  -> 

move . 1 

al, (a7) 

;result=buf fer 

movea . 1 

rf_Dir (aO) ,a0 

; directory  string 

CopyDir 

move .  b 

(a0)+, (al)  + 

;  copy 

bne.s 

.CopyDir 

subq . 1 

#l,al 

; return  empty  byte 

cmpi .b 

#' : • ,-l(al) 

; check  ending 

beq.s 

.Okay 

;if  drive  -> 

cmpi .b 

#'/',-l(al) 

,-  check  ending 

beq .  s 

.Okay 

;if  dir  -> 

move . b 

#V,  (al)  + 

; insert  separator  byte 

Okay 

movea . 1 

dl,aO 

,-  FileRequestr 

movea . 1 

rf_File(aO)  , 

aO 

; filename 

CopyFili 

5 

move . b 

(a0)+, (al)+ 

; append 

bne.s 

.CopyFile 

Cancel 

movea . 1 

dl,aO 

; 

jsr 

_LV0FreeFile 

(Request  (a6) 

;free  FileRequestr 

Error 

movem . 1 

(a7)+,d0/a0 

; clear  stack 

tst  .1 

dO 

;set  CCR 

rts 

This  routine  can  be  easily  modified  to  create  requesters  to  serve  your 
own  needs. 


*  * 

**   _. 

File  selection  with  a  modified  requester 

*  * 

*  * 

Input : 

A6=_AslBase 

*  * 

*  * 

Al=Buf fer  (FCHARS+DSIZE+1) 

*  * 

*  • 

AO=TagItems 

*  * 

*  * 

Output : 

D0=Buffer  or  NULL 

*  * 

** 

A6=_AslBase 

*  * 

*  * 

A0=Buf fer 

*  * 

*  * 



....___. „  _  _ 

.File  selection 
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clr.b 

(al) 

; 0  bytes  in  buffer 

movent .  1 

d0/al,-(a7) 

;result+buf f er 

moveq 

#ASL_FileRequest 

dO 

;Tags  in  aO 

jsr 

_LVOAllocAslRequest (a6) 

;get  FileRequestr 

move . 1 

dO, (a7) 

; save  result 

beq.  s 

.Error 

;on  error  -> 

movea . 1 

dO,aO 

;move  FileRequestr  to  aO 

jsr 

_LV0RequestFile(a6) 

,- display 

movem . 1 

(a7) ,aO-al 

;FileRequestr+buf fer 

move . 1 

aO,dl 

;save  FileRequestr 

move . 1 

dO, (a7) 

;test  Okay /Cancel 

beq.s 

.Cancel 

;on  error  -> 

move . 1 

al, (a7) 

;result=buf fer 

movea . 1 

rf_Dir (aO) ,a0 

; directory  string 

CopyDir 

move . b 

(a0)+, (al)+ 

;  copy 

bne .  s 

.CopyDir 

subq . 1 

#l,al 

; return  empty  byte 

cmpi .b 

#'  :  '  , -l(al) 

; check  ending 

beq.s 

.Okay 

;if  drive  -> 

cmpi .b 

#'/',-l(al) 

; check  ending 

beq.  s 

.Okay 

;if  dir  -> 

move .  b 

#'/', (al)  + 

;else  insert  separator  b 

Okay 

movea . 1 

dl,aO 

,-  FileRequestr 

movea .  1 

rf_File(aO)  ,a0 

; filename 

.CopyFil 

5 

move . b 

(a0)+, (al)+ 

; append 

bne.s 

.CopyFile 

.Cancel 

movea . 1 

dl,aO 

; 

jsr 

_LVOFreeFi leRequ 

est (a6) 

; f ree  FileRequestr 

.Error 

movem . 1 

(a7)+,dO/aO 

; clear  stack 

tst.l 

dO 

;set  CCR 

rts 

The  address  of  a  Tagltem  field  is  expected  as  an  additional  parameter. 
Here  is  an  example  of  how  this  can  look: 


.FileReqTags 

del   ASL_Hail,_Titletext 
del   ASL_Dir,_DirName 
del   ASL_OKText , _Okay 
del   ASL_CancelText,_Cancel 
del   TAG_DONE 


title  text  for  the  requester. 

path 

OK  button 

CANCEL  button. 

end  of  field 
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_Titletext  dc.b  'Load  file',0 

_Okay      dc .  b  '  Load  ■ ,  0 

_Cancel    dc.b  ' Return ',0 

_DirName   dc.b  'Work:',0 


3.1.2  The  Commodities  Library 


The  utilities  found  in  the  Commodities  directory  of  the  Workbench  are 
used  to  manipulate  input  queries  for  the  A3000.  These  routines  have 
been  gathered  into  a  library.  This  allows  you  to  add  your  own 
expansions  to  the  Commodities  utilities. 

The  name  "Commodities  Library"  is  often  shortened  to  Cx  library.  The 
base  address  is  expected  in  register  A6  with  all  function  calls. 

Functions  of  the  Commodities  Library 


1.  Object  Functions 

CreateCxObj 

CxBroker 

ActivateCxObj 

DeleteCxObj 

DeleteCxObjAll 

CxObjType 

CxObjError 

ClearCxObjError 

SetCxObjPri 

2.  Object  Linking 

AttachCxObj 
EnqueueCxObj 
InsertCxObj 
RemoveCxObj 

3.  Special  Functions 

FindBroker 

SetTranslate 

SetFilter 

SetFilterIX 

ParseDC 


4.  General  Messages 

CxMsgType 
CxMsgData 
CxMsgID 

5.  Message  Paths 

DivertCxMsg 
RouteCxMsg 
DisposeCxMsg 

6.  InputEvent  Processing 

InvertKeyMap 
AddlEvents 

7.  Control  Program  Functions 

CopyBrokerList 

FreeBrokerList) 

BrokerCommand 
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8.  Standard  Macros  CxSignal 

CxTranslate 
CxFilter  CxDebug 

CxTypeFilter  CxCustom 

CxSender 

Description  of  Functions 

7.  Object  Functions 

[CreateCxObj  Create  Commodities  object | 

Call:  co  =  CreateCxObj  (type,    argl,    arg2) 

DO         -30 (A6)  DO  A0  Al 

STRUCT   CxObj    *CO 
ULONG      type 
LONG       argl 
LONG       arg2 

Function:      Creates  a  Commodities  of  type  'type'. 

Parameters:  type  Object  type 

args  Object  arguments 

Result:  Address  of  a  CxObj  structure,  a  type  of  handle  for  Cx 

objects.  A  result  of  0  indicates  a  system  error,  such  as  lack 
of  memory. 

See  also:  CxObjError(),  CxFilter(),  CxTypeFilter(),  CxSender(), 
CxSignal(),  CxTranslate(),  CxDebugO,  CxCustom(), 
CxBrokerO 

fCxBroker  Create  CxObj  of  type  broker  | 

Call:  broker  =  CxBroker(nb,    error); 

DO  -3  6 (A6)      A0      DO 

STRUCT  CxObj  *broker 
STRUCT  NewBroker  *nb 
LONG        *error 


37 


3.  Programming  with  AmigaOS  2jc 


Function:  Creates  a  broker  according  to  the  information  passed  in  the 
NewBroker  structure.  As  opposed  to  a  normal  CxObj,  a 
broker  is  inactive  when  created. 

Parameters:  nb  NewBroker  structure  used  to  define  the  broker. 

error  Address  of  error  code  or  0. 

Dec  Hex  STRUCTURE  NewBroker , 0 

0  $0  BYTE  nb_Version   /version  5 

1  $1  BYTE  nb_Pad 

2  $2  APTR  nb_Name      ;  Broker  name 

6   $6  APTR  nb_Title    ; strings,  description  of 
10   $A  APTR  nb_Descr     ;the  application 
14   $E  SHORT  nb_Unique    ;what  happens  with  a  Broker  of 

;the  same  name 
16  $10  WORD   nb_Flags 

18  $12  BYTE  nb_Pri       .-priority  in  the  object  list 

19  $13  BYTE   nb_Pad2 

20  $14  APTR  nb_Port      ,-MsgPort 
24  $18  WORD  nb_ReservedChannel 

Result:  Address  of  a  CxObj  structure,  or  0  in  the  case  of  an  error. 

If  you  specify  an  address  in  error,  the  following  codes  will 
be  used  at  this  address: 

CBERR_OK    No  error,  broker  was  created. 

CBERR_SYSERR 

System  error,  such  as  lack  of  memory. 

CBERR_DUP 

Duplicate  definition  with  this  name. 

CBERR_VERSION 

Unknown  version  number. 

See  also:  Brokers  and  Application  Sub-Trees  (in  the  Reference 
Manual). 
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|  ActivateCxObi  Activate  object  functions | 

Call:  previous  =  ActivateCxObj  (co,    true); 

DO  -42 (A6)  AO      DO 

STRUCT   CxObj    *CO; 
BOOL        true ; 

Function:  Every  Commodities  object  can  be  activated  and 
deactivated.  If  it's  active,  it  executes  a  specific  operation 
when  a  Commodities  message  is  received.  This  function  is 
used  to  activate  and  deactivate  objects. 

Parameters:  co  CxObj  structure  of  the  object  whose  activation 

you  want  to  control. 

true  Boolean  argument.  A  value  of  0  indicates 

inactivation. 

Result:  previous     Previous  status 

See  also:       CxBroker() 

iDeleteCxObj  Delete  Commodities  object| 

Call:  DeleteCxObj (co) ; 

-48 (A6)  AO 

STRUCT  CxObj    *CO; 

Function:     Deletes  a  selected  Commodities  object.  If  this  object  is  part 
of  a  list,  it's  also  removed  from  the  list. 

If  the  object  has  some  other  underlying  substructure(s)  in 
the  system  hierarchy,  then  DeleteCxObjAH()  must  be  used. 

Parameters:  co  CxObj 

Result:  None.  Invalid  parameter  may  cause  system  crash. 

See  also:       exec.library/Remove(),  DeleteCxObj All() 


39 


3.  Programming  with  AmigaOS  2.x 


DeleteCxObjAH 


Delete  Commodities  object  and  all  underlying  substructures 


Call:  DeleteCxObjAll(co)  ,• 

-54 (a6)  aO 

STRUCT   CxObj    *co; 

Function:  Deletes  a  selected  Commodities  object.  If  the  object  is  part 
of  a  list,  it's  also  removed  from  the  list. 

If  the  object  has  some  other  underlying  substructure(s)  in 
the  system  hierarchy,  they  are  also  deleted. 

Parameters:  co  CxObj  structure  of  any  type. 

Result:  None.  Improper  use  of  this  function  will  crash  the  system. 

See  also:       exec.library/Remove(),  DeleteCxObjO 

ICxObjType  Get  object  type  I 

Call:  type  =  CxObjType(co)  ; 

DO  -60 (A6)         AO 

ULONG  type 
STRUCT  CxObj  *co; 

Function:  Returns  the  object  type  for  a  selected  Commodities  object. 
The  CxObj  must  be  known,  but  you  will  normally  only 
have  this  information  for  your  own  objects.  That  makes  this 
function  rather  meaningless. 

Parameters:  co  CxObj  structure 

Result:  Object  type.  If  you  pass  the  value  0  as  the  parameter,  the 

result  is  type  CXJNVALID.  This  function  only  reads  a  data 
structure.  If  you  enter  the  wrong  parameter  value,  the  result 
will  be  meaningless. 

See  also:       CreateCxObjO,  CxBrokerQ 
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ICxObjError  <H*  error  codel 

Call:  error  =  CxObj  Error  ( co )  ; 

DO  -66 (A6)  AO 

LONG        error 
STRUCT   CxObj    *co; 

Function:  When  a  function  fails,  the  cause  of  the  error  is  encoded  in 
various  different  bits.  CxObjError()  gives  you  access  to 
read  these  bits. 

Parameters:  co  CxObj  structure 

Result:  A  longword  where  the   set  bits  have  the  following 

meanings: 

COERRJSNULL 

A  value  of  0  was  passed  for  CxObj. 

COERR_NULLATTACH 

Attempt  to  enter  a  non-existent  object  in  a 
Commodities  list. 

COERR_BADFDLTER 

Bad  filter  string. 

COERR_BADTYPE 

A  type-specific  function  was  attempted  on 
an  object  of  the  wrong  type. 

See  also:       SetFilter(),  SetFilterIX(),  AttachCxObjO,  ActivateCxObjO, 
ClearCxObjError() 

IClearCxObjError  Delete  error  number  of  a  Cx  objectl 

Call:  ClearCxObj  Error  ( co )  ; 

-72 (A6)  AO 

STRUCT   CxObj    *CO; 

Function:     Deletes  the  error  code  of  a  Commodities  object. 
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Parameters:  co  CxObj  structure 

Result:  None. 

Warning:  This  routine  may  not  be  used  with  filter  objects  if  the  error 
bit  COERRjBADFILTER  is  set. 

See  also:       CxObjError() 
ISetCxObjPri  Change  priority  of  a  Cx  oTiectl 

Call:  SetCxObjPri(co,   pri) 

-78 (A6)  AO      DO 

STRUCT  CxObj  *co; 
LONG    pri; 

Function:  This  function  sets  the  priority  of  an  object  that  was  entered 
in  a  list  with  EnqueueCxObj().  The  mechanism  corresponds 
to  that  of  the  Exec  Lists  System. 

Parameters:  co  CxObj  structure 

pri  Priority  (127  through  -128) 

Result:  None. 

See  also:  ToolTypes  and  the  Commodities  Environment  (in  the 
Reference  Manual),  EnqueueCxObjO 

2.  Object  Linking 

[AttachCxObj  Attach  object  to  a  head  object  I 

Call:  AttachCxObj  (headobj  ,    co); 

-84 (A6)  AO  Al 

STRUCT  CxObj  *headobj 
STRUCT  CxObj  *co 

Function:      Attaches  an  object  to  the  end  of  the  list  of  another  object. 
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Parameters:  headobj       CxObj  structure  of  the  head  object  to  which 

this  object  will  be  attached. 

co  CxObj  structure  of  the  object  to  be  attached  as 

a  sub-object. 

Result:  If  co  is  0,  then  the  error  is  noted  in  headobj.  This  can  be 

queried     with     CxObjError()     and     cleared     with 
ClearCxObjError(). 

See  also:       exec.library/AddTail(),  Objects  and  Messages  (in  the 
Reference  Manual),  CxObjError(),  ClearCxObjError() 

lEnqueueCxObj  Enter  object  as  a  sub-object| 

Call:  EnqueueCxObj  (headobj  ,    co); 

-90 (A6)  A0  Al 

STRUCT  CxObj    *headobj 
STRUCT   CxObj    *CO 

Function:  Enters  an  object  in  the  list  of  another  object  according  to 
its  priority. 

Parameters:  headobj      CxObj   structure  of  the  head  object  that 

possesses  the  sub-object  list. 

co  CxObj  structure  of  the  object  to  be  entered  in 

the  sub-object  list. 

Result:  If  co  has  a  value  of  0,  the  error  is  noted  in  headobj.  This  can 

be    queried    with    CxObjError()    and    cleared    with 
ClearCxObjErrorO. 

See  also:  exec.library/Enqueue(),  SetCxObjPri(),  Objects  and 
Messages  (in  the  Reference  Manual),  CxObjError(), 
ClearCxObjErrorO 

llnsertCxObj  Insert  an  object  in  front  of  another  object! 

Call:  insertCxObj  (headobj  ,    co,   pred) ; 

-96  (A6)  A0  Al      A2 
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STRUCT  CxObj  *headobj 
STRUCT  CxObj  *co 
STRUCT  CxObj  *pred 

Function:  The  object  co  is  inserted  as  a  sub-object,  in  the  list  of  object 
headobj,  in  front  of  sub-object  pred. 

Parameters:  headobj      CxObj  structure  that  possesses  the  sub-object 

list 

co  Object  to  be  entered  in  the  list. 

pred  Sub-object  in  front  of  which  co  is  inserted. 

Result:  If  co  has  a  value  of  0,  the  error  is  noted  in  headobj.  This  can 

be    queried    with    CxObjError()    and    cleared    with 
ClearCxObjErrorO. 

Warning:  Since  the  Exec  function  Insert()  needs  the  list  header,  the 
headobj  may  not  be  0  in  cases  where  pred  is  0. 

See  also:  exec.library/Insert(),  Objects  and  Messages  (in  the 
Reference  Manual),  CxObjError(),  ClearCxObjErrorO 

IRemoveCxObj  Remove  an  object  from  a  list| 

Call:  RemoveCxOb j  ( co )  ; 

-102 (a6)  A0 

STRUCT  CxObj    *co 

Function:  Removes  a  Commodities  object  from  a  selected  list.  This 
function  will  not  crash  if  you  pass  it  a  value  of  0  or  the 
value  of  an  object  not  found  in  the  list. 

Parameters:  co  CxObj  structure  of  the  object  to  be  removed. 

Result:  None. 

Warning:  This  routine  was  not  intended  to  remove  a  broker  from  the 
master  list. 
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See  also:       Objects  and  Messages  (in  the  Reference  Manual) 

3.  Special  Functions 

fFindBroker  Find  the  broker  with  a  given  name  | 

Call:  broker=FindBroker  (name) 

DO  -108 (A6)        A0 

STRUCT  CxObj    *broker 

APTR       name 

Function:      Returns  the  address  of  a  broker  when  you  know  its  name. 

Parameters:  name  Address  of  the  name  string. 

Result:  broker         CxObj  structure  of  the  broker  or  0. 

See  also:       exec.library/Find  function 

[SetTranslate  Replace  the  translation  list | 

Call:  Error  =  SetTranslate  (translator,  ie) ; 

DO       -114 (a6)      A0  Al 

LONG  Error 

STRUCT  CxObj  *translator 

STRUCT  IX  *ie 

Function:  Replaces  the  translation  list  of  a  translator  object  with  the 
list  at  address  ie.  If  a  value  of  0  is  passed  for  ie,  then  all 
events  are  taken.  The  InputEvents  are  copied  to 
Commodities  messages  during  the  translation. 

Parameters:  translator    CxObj  structure  of  a  translator  object. 

ie  InputEvent  list 

Result:  0  if  the  function  was  successfully  executed. 

See  also:       InputDevice/InputEvent,  CxTranslateQ 
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|  SetFilter  Set  pattern  matching  for  a  filter  objectl 

Call:  SetFilter  (filter,  text); 

-120 (A6)   A0      Al 

STRUCT  CxObj  * filter 
APTR   text 

Function:  Sets  the  pattern  matching  according  to  the  pattern  string 
passed  in  text. 

Parameters:  filter  CxObj  structure  of  a  filter  object. 

text  Pattern  string 

Result:  None.  A  bad  filter  error  can  be  queried  with  CxObjError() 

(COERR.BADFILTER). 

See  also:  SetFilterIX(),  CxObjError(),  Commodities  Input  Messages 
and  Filters,  Input  Expressions  and  Description  Strings  (in 
the  Reference  Manual) 

|  SetFilterIX  Set  pattern  matching  of  a  filter  objectl 

Call:  error  =  SetFilterIX  (filter,  ix) ; 

DO     -126 (A6)   A0      Al 

STRUCT  CxObj  *filter 
STRUCT  IX  *ix 

Function:  Sets  the  pattern  matching  according  to  the  contents  of  the 
Input  Expression  structure. 

Parameters:  filter  CxObj  structure  of  a  filter  object. 

ix  Input  Expression  structure 

Result:  error  0  or  error  number 

See  also:  SetFilter(),  CxObjError(),  Commodities  Input  Messages  and 
Filters,  Input  Expressions  and  Description  Strings  (in  the 
Reference  Manual) 
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fParselX  Translate  string  with  IX  structure] 

Call:  failurecode  =  ParselX (string,  ix) ; 

DO  -132 (A6)  AO      Al 

LONG   failurecode 
APTR   string 
STRUCT  IX  *ix 

Function:      Translates  the  parts  of  a  given  string  to  an  IX  structure. 

Parameters:  string  The  string  to  be  processed. 

ix  Input  Expression  structure 

Result:  0  if  no  error  occurred. 

See  also:       Input  Expressions    and   Description    Strings    (in   the 
Reference  Manual) 

4.  General  Messages 

[CxMsgType  Query  Commodities  message  type| 

Call:  type  =  CxMsgType(cxm) 

DO  -138 (A6)      AO 

ULONG      type 
STRUCT   CxMsg    *cxm 

Function:      Returns  the  Commodities  message  type. 

Parameters:  cxm  Address  of  a  Commodities  message. 

Result:  Message  type,  0  in  the  case  of  an  invalid  message. 

See  also:       CxMsgData(),  CxMsgID() 

[CxMsgData  Obtain  the  data  address  for  a  CxMsgl 

Call:  contents  =  CxMsgData (cxm) ; 

DO  -144 (A6)      AO 
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APTR   contents 
STRUCT  CxMsg  *cxm 

Function:  Most  Commodities  messages  contain  data,  for  example  an 
InputEvent  structure.  CxMsgData()  can  be  used  to  return  a 
pointer  to  this  data. 

Parameters:  cxm  Address  of  a  CxMsg. 

Result:  Address  of  the  data;  0  in  the  case  of  an  invalid  message. 

Warning:  If  a  message  is  received  from  a  sender  object,  the  address 
cannot  be  used  after  the  reply  is  made. 

See  also:       CxSender(),  CxCustom() 

[CxMsglD  Obtain  the  source  identification  of  a  CxMsg | 

Call:  id  =  CxMsgiD(cxm)  ,• 

DO         -150 (A6)    A0 

LONG        id 

STRUCT  CxMsg  *cxm 

Function:  Returns  the  source  identification  code  specified  by  an 
application  for  a  message. 

Parameters:  cxm  Address  of  a  CxMsg. 

Result:  ID  of  the  message;  0  if  the  message  has  no  ID. 

See  also:       CxSender(),  CxCustom() 
5.  Message  Paths 

[DivertCxMsg  Send  a  message  to  a  sub-object  | 

Call:  DivertCxMsg  (cxm,   headobj  ,    returnobj) 

-156  (A6)  A0        Al  A2 

STRUCT  CxMsg  *cxm 
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STRUCT  CxObj  *headobj 
STRUCT  CxObj  *returnobj 

Function:  Sends  a  CxMsg  to  objects  in  the  sub-object  list  of  a 
Commodity  object.  The  message  is  sent  on  down  the  list 
until  the  next  object  is  the  specified  returnobj.  For  example, 
a  Filter  object  (named  'Filter'  for  the  sake  of  this  example) 
would  send  a  message  to  its  sub-objects  as  follows: 
DivertCxMsg(cxm,FilterJJilter). 

Parameters:  cxm  CxMsg  structure  to  be  sent. 

headobj      Head  object  that  owns  the  sub-objects  that  will 
receive  the  message. 

returnobj     SUCC  object  that  indicates  the  last  sub-object 
in  the  chain. 

Result:  None. 

See  also:       The  Reference  Manual 

|  RouteCxMsg  Set  the  next  destination  for  a  message  | 

Call:  RouteCxMsg  (cxm,    co) 

-162 (A6)         AO        Al 

STRUCT  CxMsg   *cxm 
STRUCT   CxObj    *co 

Function:      Determines  the  next  object  that  will  receive  the  message. 

Parameters:  cxm  CxMsg  to  be  sent. 

co  CxObj  that  will  be  the  next  object  to  receive 

the  message. 

Result:  None. 

See  also:       DivertCxMsgO 
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[DlsposeCxMsg  Delete  a  message  | 

Call:  DisposeCxMsg(cxm) 

-168 (A6)  AO 

STRUCT  CxMsg   *cxm 

Function:  Deletes  the  specified  Commodities  message.  This  is  good 
for  disposing  of  InputE vents  (type  CXM_E3VENT). 

Parameters:  cxm  Address  of  the  CxMsg. 

Result:  None. 

6.  InputEvent  Processing 

[InvertKeyMap  Convert  ANSI  codes  | 

Call:  retval  =  InvertKeyMap  (ansicode,    ie,    km) 

DO  -174 (A6)  DO  AO      Al 

ULONG     retval 
ULONG     ansicode 
STRUCT  InputEvent   *ie 
STRUCT  KeyMap  *km 

Function:  The  MapANSI()  function  determines  whether  an  ANSI 
code  conversion  should  take  place  when  an  InputEvent  is 
received.  The  given  KeyMap  is  used.  Simple  DeadKeys  are 
converted. 

Parameters:  ansicode     ANSI  code  to  be  checked. 

ie  InputEvent  structure  to  be  filled. 

km  KeyMap,  default  =  0 

Result:  0  No  conversion 

See  also:       InvertStringQ 
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[AddlEvents  Add  a  list  of  InputEvents  to  the  Cxflstl 

Call:  AddlEvents  (ie) 

-180 (A6)         A0 

STRUCT  InputEvent  *ie; 

Function:  Normally,  the  Commodities  Library  Input  Handler  gets  its 
information  directly  from  the  input  device.  But  it  would  not 
be  convenient  to  send  messages  to  the  Commodities 
Library  via  this  device.  Therefore,  AddlEvents  was 
implemented.  The  InputEvents  are  copied  to  the 
Commodities  messages  and  sent  to  the  objects  in  the 
internal  object  list. 

Parameters:  ie  Linked  list  of  InputEvents. 

Result:  None. 

See  also:       FreeIEvents() 
7.  Control  Program  Functions 

[CopyBrokerList  Copy  the  broker  list | 

Call:  list  =  CopyBrokerList  (blist) 

DO  -186 (A6)  A0 

Warning:      FOR  CONTROL  PROGRAMS  ONLY! 

[FreeBrokerList  Free  broker  listj 

Call:  FreeBrokerList  (list) 

-192(A6)  A0 

Warning :      FOR  CONTROL  PROGRAMS  ONLY! 

[BrokerComrnand  Broker  command"] 

Call:  result  =  BrokerComrnand  (name,  id) 

DO  -198 (A6)  A0        DO 
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Warning:      FOR  CONTROL  PROGRAMS  ONLY! 
8.  Standard  Macros 

Creation  ofCxObj: 


CxFilter(d) 
CxTypeFi Iter (type) 
CxSender (port , id) 
CxSignal (task, sig) 
CxTrans late ( ie ) 
CxDebug(id) 
CxCustom(action, id) 


CreateCxObj (CX_FILTER, d, 0 ) 
CreateCxObj (CX_TYPEFILTER, type, 0) 
CreateCxObj (CX_SEND,port, id) 
CreateCxObj (CX_SIGNAL, task, sig) 
CreateCxObj ( CX_TRANSLATE , ie, 0) 
CreateCxObj (CX_DEBUG, id, 0) 
CreateCxObj (CX_CUSTOM, action, id) 

Buffer  size  of  Broker: 


CBD_NAMELEN  =  24 
CBD_TITLELEN  =40 
CBD_DESCRLEN  =40 


CxBroker()  error: 


CBERR_OK       =0  ;no  error 
CBERR_SYSERR   =  1  ; system  error 
CBERR_DUP     =  2  ,-duplicate  definition 
CBERR_VERSION  =  3  ; unknown  version 


NB_VERSION 


=  5  /version  of  NewBroker 


Dec  Hex  STRUCTURE  NewBroker, 0 

0   $0  BYTE  nb_Version   ; vers ion  5 


1  $1  BYTE  nb_Pad 

2  $2  APTR  nb_Name 
6  $6  APTR  nb_Title 

10  $A  APTR  nb_Descr 

14  $E  SHORT  nb_Unique 


,- Broker  name 

/strings,  description  of  the 

,-application 

;what  happens  with  a  Broker  of  the 

;same  name 


16  $10  WORD  nb_Flags 

18  $12  BYTE  nb_Pri 

19  $13  BYTE  nb_Pad2 

20  $14  APTR  nb_Port      ;MsgPort 
24  $18  WORD  nb_ReservedChannel 


,-priority  in  the  Object  list 


Flags  for  nbJJnique: 


NBU_DUPLICATE  =  0  ,-duplicate  definition  allowed 
NBU_UNIQUE    =  1  ,-duplicate  definition  not  allowed 
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NBU_NOTIFY     =  2  ,-CxMsg  CXM_UNIQUE  to  existing  Broker 

Flag  for  nb_Flags: 


COF_SHOW_HIDE  =  4 


CX_INVALID  =  0 

CX_FILTER  =  1 

CX_TYPEFILTER  =  2 

CX_SEND  =  3 

CX_SIGNAL  =  4 

CXJTRANSLATE  =  5 

CX_BROKER  =  6 

CX_DEBUG  =  7 

CX_CUSTOM  =  8 

CX_ZERO  =  9 


Object  types: 

;no  object 

;  f or  InputEvent  messages  only 

/message  Type  filter 

/message  sender 

; signal  sender 

; InputEvent  translator 

;most  applications 

; sends  Debug  info  to  serial  port 

/custom  Function 

; last  entry 


CXM_UNIQUE 
CXM_I EVENT 
CXM_COMMAND 


CXCMD_DISABLE 

CXCMD_ENABLE 

CXCMD_APPEAR 

CXCMD_DISAPPEAR 

CXCMD_KILL 

CXCMD_UNIQUE 

CXCMD_LIST  CHG 


Message  Types: 

16  ;from  CxBroker ( ) 

32  ; InputEvent 

64  /from  BrokerCommand ( ) 

ID  Values: 

=  15  /deactivate 

=  17  /activate 

=  19  /open  window 

=21  /close  window 

=23  / remove 

=  25  /duplicate  definition  attempted 

=  27  /Broker  list  changed 

Results  of  BrokerCommand(): 


CMDE_OK  =  0 
CMDE_NOBROKER  =  -1 
CMDE_NOPORT  =  -2 
CMDE_NOMEM     =  -3 


Error  Flags  from  CxObj  (CxObjError()): 


COERR_ISNULL     =  1  /call  was  CxError (NULL) 
COERR_NULLATTACH  =  2  /sub-object  was  0 
COERR_BADFILTER   =  4  /invalid  Filter 
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COERR_BADTYPE 


8  ; invalid  object  type 

Version  of  IX  Structure: 


IX_VERSION  =  2 

Dec  Hex 

STRUCTURE  IX, 0 
$0  UBYTE  ix_Version 
$1  UBYTE  ix_Class 
$2  UWORD  ix_Code 


0 
1 
2 
4 
6 
8 
10 


version  2 

Event  class 

Event  data 
$4  UWORD  ix_CodeMask  ;data  mask 
$6  UWORD  ix_Qualifier;exact  description 
$8  UWORD  ix_QualMask  ;QualSame  mask 
$A  UWORD  ix_QualSame  ; Qualifier  with  the  same  meaning 


Flags  for  ixjQualSame: 


IXSYM_SHIFT  =  1  ;left  and  right  Shift  keys  together 
IXSYM_CAPS   =  2  ;Caps-Lock  at  the  same  time 
IXSYM_ALT   =  4  ; lef t  and  right  Alt  keys  together 

Corresponding  QualMasks  (see  InputEvent): 

IXSYM_SHIFTMASK  =  IEQUALIFIER_LSHIFT  I  IEQUALIFIER_RSHIFT 
IXSYM_CAPSMASK   =  IXSYM_SHIFTMASK     I  IEQUALIFIER_CAPSLOCK 
IXSYM_ALTMASK    =  IEQUALIFIER_LALT    I  IEQUALIFIER_RALT 

IX_NORMALQUALS   =  $7FFF  ; normal  QualMask 

3.1.3  The  Diskfont  Library 

The  Diskfont  Library  manages  fonts  and  font  styles,  lists  the  available 
fonts,  or  loads  a  font  in  memory  (if  it  is  not  already  loaded). 

This  library  is  opened  under  the  name  "diskfont.library".  The  base 
address  _DiskfontBase  must  be  supplied  in  the  A6  register  with  all 
function  calls. 

Functions  of  the  Diskfont  Library 

OpenDiskFont 
AvailFonts 
NewFontContents 
DisposeFontContents 


54 


3.1   The  Libraries  and  their  Functions 


NewScaledDiskFont 

Description  of  the  Functions 

|  OpenDiskFont  Load  or  scale  a  Diskfontl 

Call:  font   =  OpenDiskFont  (text Attr) 

DO  -30 (A6)  A0 

STRUCT   TextFont    *font 
STRUCT  TextAttr  *textAttr 

Function:  The  font  described  in  the  TextAttr  structure  is  loaded  in 
memory  and  its  address  is  returned.  If  desired,  the  font  is 
scaled  to  the  requested  size. 

Parameters:  textAttr       TextAttr  structure  or  TTextAttr  structure  that 

describes  the  font. 

Result:  Address  of  the  font  (TextFont  structure)  or  0  if  the  font  was 

not  found.  If  only  the  desired  font  size  was  not  found  and 
the  DESIGNED  flag  in  the  TextAttr  structure  is  not  set, 
then  the  font  of  the  desired  size  is  created  from  a  different 
size. 

Warning:  This  routine  will  only  work  with  font  names  up  to  30 
characters  long. 

See  also:       AvailFonts(),  graphics.library/OpenFont() 

|  AvailFonts  Retrieve  a  list  of  all  available  fonts| 

Call:  error  =  AvailFonts (buffer,  bufBytes,  flags); 

DO       -36 (A6)     A0      DO        Dl 

LONG  error 

STRUCT  AFH  *buffer 

LONG  bufBytes 

ULONG  flags 
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Function:  AvailFonts()  fills  a  memory  block  of  the  specified  size  and 
address  with  font  data  structures.  This  gives  the  user  a  list 
of  all  available  fonts.  Certain  flags  can  be  set  to  indicate 
where  to  look  for  fonts,  which  fonts  are  stored  in  this 
memory  block,  and  which  data  structures  to  use. 

Parameters:  buffer         Address  of  the  memory  block  that  will  contain 

the  font  list. 

bufbytes     Size  of  the  memory  block. 

flags  Flags  for  setting  the  AvailFonts()  options. 

AFF_MEMORY      Look  for  fonts  in  memory. 


AFF  DISK 


AFF  SCALED 


Look  for  fonts  in  current 
FONTS  directory. 

Include  constructed  fonts 
in  the  list. 


AFF  TAGGED 


Fill   memory   with   TAF 
(TaggedAvailFonts) 
structures  rather  than  AF 
structures. 


Result:  If  the  buffer  is  too  small,  the  number  of  bytes  missing  will  be 

returned  in  error;  otherwise  a  value  of  0  is  returned.  If  0  is 
returned,  the  buffer  is  filled  with  an  AFH  structure,  followed 
by  AF  or  TAF  structures.  Memory  resident  fonts  must  be 
opened  with  OpenFont()  and  Diskfonts  must  be  opened 
with  OpenDiskFont(). 

Warning:      If  a  certain  font  is  located  both  in  memory  as  well  as  on 
disk,  its  name  will  appear  in  the  list  twice. 

See  also:       OpenDiskFontQ,  graphics.library/OpenFontQ 
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|  NewFontContents  Recalculate  xxx.font  file  1 

Cfl//.'         fontContentsHeader  =  NewFontContents  (fontsLock, fontName) 
DO  -42 (A6)  AO         Al 

STRUCT  FontContentsHeader  *fontContentsHeader 
BPTR   fontsLock 
APTR   fontName 

Function:  Recalculates  an  array  with  FontContents.  This  array  begins 
with  an  FCH  structure,  followed  by  an  FC  structure  for 
each  size  of  the  font  with  the  given  name.  This  structure 
corresponds  to  the  file  'xxx.font'  in  the  FONTS  directory. 

Parameters:  fontsLock  BPTR  to  a  lock  structure  of  the  DOS  Library. 

This  lock  must  be  obtained  for  the  directory 
that  contains  the  font  (normally  the  "FONTS:" 
directory). 

fontName    Address  of  the  font  name  (including  the  suffix 
".font")  which  points  to  a  FontContents  file. 

Result:  Address  of  the  FCH  structure  (FontContentsHeader)  or  0, 

in  the  case  of  an  error. 

See  also:       DisposeFontContents(),  dos.library/Lock() 

|  DisposeFontContents  Free  xxx.font  buffer  | 

Call:  DisposeFontContents (fontContentsHeader) 

-48 (A6)  Al 

STRUCT  FontContentsHeader   * fontContentsHeader 

Function:  Frees  the  buffer  returned  with  the  function 
NewFontContents(). 

Parameters:  fontContentsHeader 

Structure  obtained  with  NewFontContents(). 

Result:  None. 

Warning:  The  system  will  crash  if  you  pass  an  address  not  obtained 
with  NewFontContentsQ. 


57 


3.  Programming  with  AmigaOS  2.x 


See  also:       NewFontContentsQ 


INewScaledDiskFont 


Create  scaled  (constructed)  font| 


Call:  header  =  NewScaledDiskFont  (srcFont,  destTextAttr) 

DO        -54 (A6)  AO        Al 

STRUCT  DiskFontHeader  *header 
STRUCT  TextFont  *srcFont 
STRUCT  TTextAttr  *destTextAttr 

Function:     Calculates  a  new  font  size  based  on  an  existing  size  for  the 
given  font. 

Parameters:  srcFont       Font  for  which  the  new  size  will  be  calculated. 

destTextAttr 

Attributes  of  the  new  font.  This  can  be  the 
address  of  a  TextAttr  structure  or  the  address  of 
a  TTextAttr  structure.  The  new  font  can  be 
freed  with  StripFont()  followed  by 
UnloadSeg().  TextFont  and  Segment  Address 
are  components  of  the  returned 
DiskFontHeader.  UnloadSegO  frees  all  memory 
blocks. 


Result: 


Address  of  a  DiskFontHeader  structure. 


Warning:  This  function  can  use  the  blitter.  Fonts  with  characters 
drawn  completely  outside  of  the  normal  character  region 
cannot  be  processed. 

See  also:       graphics.library/StripFont(),  dos.library/UnloadSeg() 


MAXFONTPATH  =  256  ;maximum  length  of  the  font  path  including  null  byte 
Dec  Hex 

STRUCTURE   FC,0 

0    $0  STRUCT   fc_FileName, MAXFONTPATH  ;font  name 

256  $100  UWORD   fc_YSize  ; f ont  height 

258  $102  UBYTE   fc_Style  ; style 

259  $103  UBYTE    fc_Flags  ;font  type 

260  $104  LABEL   fc_SIZEOF 
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STRUCTURE      TFC, 0 
$0   STRUCT     tfc_FileNarne,MAXFONTPATH-2    ;  f ont   name 

;if  the  following  Word  contains  a  non-zero  value, 
;then  the  Tagltems  will  be  found  at  the  end  of  tfc_FileName 
;that  is,  at  MAXFONTPATH-tfc_TagCount*TagItem_SIZEOF 
$FE  UWORD   tfc_TagCount  ; number  of  tags  including  TAG_DONE 

tfc_YSize    ;font  height 

tfc_Style     ; style 

tfc_Flags     ;font  type 

tfc_SIZEOF 


254 

256  $100  UWORD 

258  $102  UBYTE 

259  $103  UBYTE 

260  $104  LABEL 


FCH_ID   =  $f00   ;FontContentsHeader,  then  FontContents 
TFCH_ID  =  $f02   ;FontContentsHeader,  then  TFontContents 


Dec  Hex 

STRUCTURE   FCH, 0 
0   $0  UWORD    fch_FileID 
2   $2  UWORD   fch_NumEntries 
4   $4  LABEL    fch_FC 


; FontContentsHeader 

;FCH_ID  or  TFCH_ID 

.-number  of  (T)  FontContents 

; starting  here,  [T] FontContents 


DFH_ID       =  $f80 

MAXFONTNAME  =  32    ; f ont  name  including  ".font"  and  null  byte 

Dec  Hex 

STRUCTURE   DiskFontHeader, 0 
the  following  Longs  are  not  part  of  the  structure, 
but  they  precede  it  directly: 
-8  -$8  ULONG   dfh_NextSegment 

dfh_ReturnCode 

dfh_DF,LN_SIZE 

dfh_FileID 

dfh_Revision 

dfh_Segment 


-4  -$4  ULONG 

0  $0  STRUCT 
14  $E  UWORD 
16  $10  UWORD 
18  $12  LONG 
22  $16  STRUCT 
54  $36  STRUCT 
LABEL 


dfh_Name, MAXFONTNAME  ;the  name 
dfh_TF,tf_SIZEOF  ;TextFont 
dfh_SIZEOF 


;BPTR  to  the  next  segment 
; actually  MOVEQ  #0,D0  :  RTS 
;  node 
; DFH_ID 

; revision  number 
segment  address 


If  the  FSB_TAGGED  bit  is  set  in  dfh_TF.tf_Style: 

dfh_TagList  =  dfh_Segment  ; overwritten  during  loading 

Bits  and  Flags  of  the  AvailFonts  structure: 


AFB_MEMORY  =  0  ; memory  font 
AFF_MEMORY  =  1 
AFB_DISK   =  1  ;disk  font 
AFF_DISK   =  2 
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AFB_SCALED  =  2  ; constructed  font  (not  DESIGNED!) 
AFF_SCALED  =  4 

Bits  and  Flags  of  the  TaggedAvailFonts  structure: 

AFB_TTATTR  =15     /INVALID  VALUE  IN  INCLUDES!!! 
AFF_TTATTR  =  $8000 

Dec  Hex 

STRUCTURE   AF, 0  ;  AvailFonts 

0   $0  UWORD    af_Type  ;  MEMORY,  DISK,  or  SCALED 

2   $2  STRUCT  af_Attr,ta_SIZEOF  ;  TextAttr 
10   $A  LABEL    af_SIZEOF 

STRUCTURE   TAF, 0  ;  TAvailFonts 

0   $0  UWORD    taf_Type  ;  MEMORY,  DISK,  or  SCALED 

2   $2  STRUCT  taf_Attr,tta_SIZEOF  ;  TTextAttr 
10   $A  LABEL   taf_SIZEOF 

STRUCTURE   AFH, 0        ;  AvailFontsHeader 
0   $0  UWORD   afh_NumEntries  ;  number  of  elements 
2   $2  LABEL   afh_AF         ;  starting  here,  [T] AvailFonts 

Example 

You  can  make  it  difficult  on  yourself  and  create  a  special  font  for  each 
application,  or  you  can  handle  it  quite  easily.  We  will  now  create  a  font 
similar  to  the  Diamond  font,  but  with  a  character  height  of  only  10  pixels. 


movea.l  _DiskfontBase,a6 

lea     _TextAttr(pc) ,a0 

jsr     _LVOOpenDiskFont(a6)  ;Font=OpenDiskFont (TextAttr) 

move .1   dO , _Diamondl 0 

beq     _Fehler 

movea.l  _Gf xBase, a6 

movea.l  _Diamondl0,al 

jsr     _LVOCloseFont (a6)     ;CloseFont (Font) 

_TextAttr  dc . 1  _FontName    ; ta_Name 
dew  10  ;ta_Size 

; ta_Sty le , ta_Flags 
dc . b  FS_NORMAL , FPF_PROPORTIONAL ! FPF_DISKFONT 

_FontName  dc . b  ' diamond . font ' , 0 
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Simple,  isn't  it?  The  change  in  size  takes  only  a  fraction  of  a  second,  so  it 
does  not  add  any  appreciable  time  to  the  process. 


3.1.4  The  DOS  Library 


The  DOS  Library  is  completely  new  and  expanded  for  Kickstart  Version 
2.0.  The  DOS  Library  was  written  in  the  compiler  language  BCPL  for  the 
old  1.x  versions.  This  slow-executing  language  was  replaced  with  faster 
C  code,  but  in  order  to  maintain  compatibility,  the  BCPL  variable 
management  had  to  be  kept  for  the  most  part.  BCPL  manages  addresses 
in  numbers  of  longwords  (32  bits  =  4  bytes),  so  the  address  40  would  be 
assigned  the  number  10  in  BCPL.  This  is  why  every  address  must  be 
divisible  by  4. 

An  important  change  came  with  the  transition  to  C.  Starting  with  OS  2.0, 
DOS  expects  the  base  address  of  the  DOS  Library  to  be  passed  in  register 
A6.  This  prevents  the  use  of  faster  code  by  placing  the  base  address  in 
A5.  Programs  that  utilize  this  will  crash  under  Kickstart  2.0. 

Functions  of  the  DOS  Library 

1.  DOS  Structures  UnLockDosList 


AllocDosObject 

DupLock 

DupLockFromFH 

FreeDosEntry 

FreeDosObject 

MakeDosEntry 

2.  Logical  Devices 

AddDosEntry 

AssignAdd 

AssignLate 

AssignLock 

AssignPath 

AttemptLockDosList 

FindDosEntry 

LockDosList 

NextDosEntry 

RemDosEntry 


3.  Handlers  and  Filesystems 

AddBuffers 

DeviceProc 

DoPkt 

EndNotify 

Format 

FreeDeviceProc 

GetConsoleTask 

GetDeviceProc 

GetFileSysTask 

Inhibit 

IsFileSystem 

Relabel 

ReplyPkt 

SendPkt 

SetConsoleTask 

SetFileSysTask 

StartNotify 
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WaitPkt 

Readltem 

Selectlnput 

4.  Directories 

SelectOutput 

SetArgStr 

CreateDir 

SetCurrentDirName 

CurrentDir 

SetProgramDir 

ExAll 

SetProgramName 

Examine 

SetPrompt 

ExNext 

SystemTagList 

GetProgramDir 

VPrintf 

Info 

MatchEnd 

7.  Files 

MatchFirst 

MatchNext 

ChangeMode 

ParentDir 

Close 

ParentOfFH 

DeleteFile 

ExamineFH 

5.  Programs 

FGetC 

Flush 

AddSegment 

FPutC 

CreateNewProc 

FRead 

CreateProc 

FWrite 

Exit 

Islnteractive 

FindSegment 

Lock 

InternalLoadSeg 

LockRecord 

InternalUnLoadSeg 

LockRecords 

LoadSeg 

Open 

NewLoadSeg 

OpenFromLock 

RemSegment 

Read 

RunCommand 

Rename 

UnLoadSeg 

SameLock 

Seek 

6.CU 

SetComment 

CheckSignal 
Cli 

SetFileDate 
SetFileSize 

Execute 

SetProtection 

FindCliProc 

UnGetC 

Input 

UnLock 

MaxCli 

UnLockRecord 

Output 

UnLockRecords 

Pao/1  Arno 

VFPrintf 
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VFWritef 
Write 

5.  Strings 

AddPart 

DateToStr 

Fault 

FGets 

FilePart 

FindArg 

FPuts 

GetArgStr 

GetCurrentDirName 

GetProgramName 

GetPrompt 

MatchPattern 

NameFromFH 

NameFromLock 

ParsePattern 

PathPart 
SplitName 

Description  of  Functions 

1.  DOS  Structures 


StrToDate 
StrToLong 

9.  Time 

CompareDates 
DateStamp 
Delay 
WaitForChar 

10.  Environment  Variables 

DeleteVar 
FindVar 
GetVar 
SetVar 

11.  Errors  and  Requesters 

ErrorReport 

IoErr 

PrintFault 

PutStr 

SetloErr 


lAllocDosObject 


Create  DOS  data  structure 


Call:  ptr  =  AllocDosObject  (type,    tags) 

DO  -228 (A6)  Dl  D2 

APTR        ptr 

ULONG      type 

STRUCT  Tagltem  *tags 

Function:      Creates  one  of  several  possible  DOS  structures. 

Parameters:  type  Structure  type 

tags  TagList  address 
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Result:  Data  structure  address  or  0. 

See  also:       FreeDosObject(),  dos/dostags.h,  dos/dos.h 

Example:      Creating  a  control  structure  for  calling  the  new  ExAll() 
function: 


movea . 1  _DosBase , a  6 

moveq    #DOS_EXALLCONTROL,dl 

move . 1   #_Dummy,d2  ;save  it 

jsr     _LVOAllocDosObject (a6) 

move.l      dO,_ExAHControl 

beq  _Error 


_Dummy   dc . 1  TAG_DONE 


; empty  Tagltem  field 


|DupLock 


Copy  lock] 


Call:  newlock  =  DupLock(   lock   ) 

DO  -96 (A6)      Dl 

BPTR  newlock 
BPTR  lock 

Function:      Copy  a  Filesystem  SHAREDJLOCK. 

Parameters:  lock  Lock  to  be  copied. 

Result:  Copy  of  the  lock  or  0. 

See  also:       LockQ,  UnLockQ 


IDupLockFromFH 


Copy  a  FileHandle  lock| 


Call: 


lock  =  DupLockFromFH(fh) 
DO      -372 (A6)       Dl 

BPTR  lock 
BPTR  fh 


Function: 


Returns  a  copy  of  a  FileHandle  lock.  The  file  must  be  open 
and  accessible  to  other  programs. 
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Parameters:  fh  FileHandle  that  owns  the  lock  to  be  copied. 

Result:  Lock  or  0,  in  the  case  of  an  error. 

IFreeDosEntry  Free  a  structure  created  with  MakeDosEntryQl 

Call:  FreeDosEntry  (dlist) 

-702 (A6)  Dl 

STRUCT   DosList    *dlist 

Function:  Frees  the  result  of  a  MakeDosEntryO  call.  This  routine 
should  not  be  used.  Instead,  use  FreeDosObject()  with  the 
corresponding  value. 

Parameters:  dlist  DosList  structure  to  be  freed. 

FreeDosObject  Free  a  DOS  structure] 


Call:  FreeDosObject  (type,    ptr) 

-234 (A6)  Dl  D2 

ULONG  type 
APTR   ptr 

Function:     Frees  a  structure  created  with  AllocDosObject(). 
Parameters:  type  Type  as  specified  with  AllocDosObject(). 

ptr  Result  of  AllocDosObject(). 

See  also:       AllocDosObject(),  dos/dos.h 
Example:      Free  an  ExAU()  control  structure: 


movea . 1  _DosBase , a  6 

moveq   #DOS_EXALLCONTROL,dl 

move . 1  _ExAl IControl , d2 

jsr     _LVOFreeDosObject (a6) 
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|  MakeDosEntry  Create  a  DosList  structure  | 

Call:  newdlist  =  MakeDosEntry  (name,    type) 

DO  -696 (A6)  Dl  D2 

STRUCT  DosList   *newdlist 
APTR       name 
LONG       type 

Function:  Creates  a  DosList  structure  with  BSTR  dol_Name  and 
dol_Type.  This  function  should  not  be  used.  Instead,  use 
AUocDosObject(). 

Parameters:  name  Name  of  the  device/volume/assign  node. 

type  Entry  type 

Result:  DosList  structure  or  0. 

Type  for  AllocDosObject(): 


DOS_FILEHANDLE 

=  0 

;FileHandle 

DOS_EXALLCONTROL 

=  1 

;ExAllControl 

DOS_FIB 

=  2 

;FileInfoBlock 

DOS_STDPKT 

=  3 

; Standard  Packet 

DOS_CLI 

=  4 

;CommandLineInterface 

DOS_RDARGS 

=  5 

; in  case  arguments  were  entered 

Tags  for  AllocDosObject(): 

ADO_Dummy       =  TAG_USER+2000 

ADO_FH_Mode     =  ADO_Dummy+l  ; f or  FileHandle  only 
ADO_DirLen      =  ADO_Dummy+2  ;size  of  CurrentDir  buffer 
ADO_CommNameLen  =  ADO_Dummy+3  ;size  of  CommandName  buffer 
ADO_CommFileLen  =  ADO_Dummy+4  ;size  of  BatchFile  buffer 
ADO_PromptLen   =  ADO_Dummy+5  ;size  of  Prompt  buffer 

2.  Logical  Devices 

|  AddDosEntry  Add  an  entry  to  the  list  of  logical  devices | 

Call:  success   =  AddDosEntry  (dlist) 

DO  -678 (A6)  Dl 
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BOOL        success 
STRUCT   DosList    *dlist 

Function:  Adds  a  device,  volume,  or  assign  node  to  the  DOS  list  of 
logical  devices.  If  a  logical  device  of  the  same  name  already 
exists,  the  function  will  fail.  Exceptions  to  this  are  volumes 
nodes  with  different  dates  and  DeviceNode  names.  This 
function  can  be  called  without  a  lock  on  the  device  list. 


Parameters:  dlist 
Result:  0 


Entry  for  the  device  list. 
Error 


|  Assign  Add 


Add  a  path  to  a  directory  with  many  paths! 


Call:  success  =  AssignAdd  (name,  lock) 

DO  -630 (A6)       Dl        D2 


BOOL  success 
APTR  name 
BPTR   lock 

Function:  Sets  a  lock  on  a  directory  in  an  assign  list.  The  assign 
structure  must  be  created  with  AssignLock()  or 
AssignLate(),  and  the  lock  may  not  be  used  again  after  this. 
If  you  need  it,  you  can  create  another  copy  with 
DupLockQ. 


Parameters:  name 


Result: 

See  also: 
Example: 


lock 
0 


DeviceName  without ':' 

Lock  indicated  by  the  name. 

Error,  then  the  lock  must  be  freed  with 
UnLockQ. 


AssignLock(),  AssignLate(),  Lock(),  UnLock() 

This  allows  you  to  define  a  logical  device,  such  as  'C:'  or 
'DEVS:'  that  consists  of  several  physical  directories. 
Consider  the  following  two  directories: 
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Strings:  (DIR) 


GibsonGuitar . 8SVX 
RichGuitar.8SVX 
WarwickBass . 8SVX 
WashburnGuitar . 8SVX 


Drumkit:  (DIR) 


PaisteCymbal . 8SVX 
PaisteGong.8SVX 
PearlDrum.8SVX 
PremierDrum . 8SVX 


We  can  assign  these  two  directories  to  the  logical  device  'Samples:'  as 
follows: 


.MultiPath 

movea . 1 

_DosBase, a6 

move . 1 

#_BasePath,dl 

moveq 

#SHARED_L0CK,d2 

jsr 

_LV0Lock(a6) 

;Lock( "Strings: " , -2) 

move . 1 

d0,d2 

beq.  s 

. Error 

move . 1 

#_Samples,dl 

jsr 

_LVOAss ignLock ( a6 ) 

;AssignLock( "Samples 

' , Lock) 

tst.l 

dO 

beq.s 

.  Error2 

move . 1 

#_AddPath,dl 

moveq 

#SHARED_LOCK,  d2 

jsr 

_LV0Lock(a6) 

;Lock( "Drumkit : " , -2) 

move . 1 

d0,d2 

beq.s 

. Error3 

move . 1 

#_Samples,dl 

jsr 

_LV0AssignAdd(a6) 

;AssignAdd( "Samples" 

Lock) 

tst.l 

dO 

beq.s 

. Error4 

moveq 

#0,d0 

rts 

Error4 

Error2 

move . 1 

d2,dl 

jsr 

_LV0Unlock(a6) 

Errorl 
moveq 

#-l,dO 

Error3 

rts 
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_BasePath  dc.b  'Strings: ',0 
_AddPath  dc  .b  '  Drurnkit :  '  ,  0 
_Samples     dc . b    ' Samples • , 0 


If  no  errors  occurred  (result=0),  you  can  access  these  files  as  follows: 


" Samples :WarwickBass . 8SVX" 
"Samples : PaisteCymbal . 8SVX" 


If  you  were  to  store  a  file  in  the  logical  device  'Samples',  it  would  go  to 
the  physical  directory  set  with  AssignLock().  In  this  case,  this  is 
"Strings:". 

lAssignLate  Pre-define  an  AssignLock] 

Call:  success  =  AssignLate  (name,  path) 

DO  -618 (A6)         Dl        D2 

BOOL  success 
APTR  name 
APTR  path 

Function:  Defines  an  AssignLock  that  is  only  created  after  the  first 
access  on  the  given  path.  This  is  very  helpful  in  cases 
where  a  device  hasn't  been  activated  yet. 

Parameters:  name  DeviceName  without ':' 

path  Name  used  to  address  the  device. 

Result:  0  Error 

See  also:       AssignLock 

|  AssignLock  Assign  a  name  to  a  lock| 

Call:  success  =  AssignLock (name, lock) 

DO  -612 (A6)         Dl        D2 

BOOL  success 
APTR  name 
BPTR  lock 
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Function:  Assigns  a  name  to  a  lock.  A  value  of  0  for  lock  will  delete 
the  entry  with  the  given  name.  If  an  entry  with  the  same 
name  exists,  it's  replaced  with  the  new  lock.  After  this 
function,  the  lock  may  not  be  used  again.  If  necessary, 
make  a  copy  with  DupLock(). 

Parameters:  name  Device  name  (without ':')  to  which  the  lock  is 

assigned. 

lock  Lock  for  the  name. 

Result:  0  Error,  lock  must  then  be  freed  with  UnLock(). 

See  also:       Lock(),  DupLock(),  UnLock() 

|  AssignPath  Assign  a  name  to  a  path  | 

Call:  success   =  AssignPath  (name, path) 

DO  -624 (A6)         Dl        D2 

BOOL  success 
APTR  name 
APTR  path 

Function:  Assigns  a  name  to  a  path.  Also  works  with  disks  (volumes) 
that  are  not  yet  known. 

Parameters:  name  Device  name  without ':' 

path  Path  name  replaced  by  'name'. 

Result:  0  Error 

See  also:       AssignLock(),  AssignLate() 

|  AttemptLockDosList  Lock  a  directory  list| 

Call:  dlist  =  AttemptLockDosList  (flags) 

DO  -666 (A6)  Dl 

STRUCT   DosList    *dlist 
ULONG     flags 
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Function:      Prevents  certain  access  from  other  programs  to  the  list  of 
logical  devices. 

Parameters:  flags  Flags  that  indicate  the  nodes  to  be  locked. 

Result:  dlist  Start  of  the  list  or  0  (no  node  address). 

See  also:       LockDosListQ,  UnLockDosListQ 


IFindDosEntry 


Call:  newdlist  =  FindDosEntry (dlist, name, flags) 

DO  -684 (A6)  Dl  D2        D3 

STRUCT  DosList   *newdlist, *dlist 
APTR        name 
ULONG     flags 

Function:      Returns  an  entry  from  the  list  of  logical  devices. 
Parameters:  dlist  Starting  entry  for  the  search. 

name  Device  name  without ':'. 

flags  Flags  previously  passed  to  LockDosList(). 

Result:  Address  of  the  entry  or  0. 

ILockDosList  Allow  access  to  list  of  logical  devices  | 

Call:  dlist  =  LockDosList  (flags) 

DO  -654 (A6)  Dl 

STRUCT   DosList    *dlist 

ULONG     flags 

Function:  This  function  allows  exclusive  access  to  the  list  of  logical 
devices.  If  another  task  has  the  access  rights,  the  program 
waits  until  the  list  is  freed  with  UnLockDosList().  You  can 
use  nested  calls  of  this  function. 

Parameters:  flags  Entries  to  be  accessed. 
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Result:  Pointer  to  the  list  header,  not  an  entry. 

INextDosEntry  Next  entry  in  the  logical  device  list| 

Call:  newdlist  =  NextDosEntry (dlist, flags) 

DO  -690 (A6)  Dl  D2 

STRUCT  DosList    *newdlist , *dlist 
ULONG     flags 

Function:  Finds  the  next  entry  of  the  desired  type  in  the  logical 
device  list. 

Parameters:  dlist  Current  entry. 

flags  Type,  see  FindDosEntry(). 

Result:  Next  DosList  structure  or  0. 

|  RemDosEntry  Remove  a  DosList  structure  from  the  list  | 

Call:  success   =  RemDosEntry  (dlist) 

DO  -672 (A6)  Dl 

bool       success 
STRUCT    DosList    *dlist 

Function:  This  function  can  be  used  to  remove  an  entry  from  the 
logical  device  list.  LockDosList()  must  be  called  first.  The 
memory  block  used  is  not  freed  with  this  function. 

Parameters:  dlist  DosList  structure. 

Result:  0  Error 

|UnLockDosList  Free  logical  device  list! 

Call:  UnLockDosList  ( flags) 

-660 (A6)  Dl 

ULONG  flags 
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Function:      Frees    a   logical   device    list   that   was    locked   with 
LockDosList(). 

Parameters:  flags  Flags  that  were  specified  with  LockDosListQ. 


Dec 

Hex 

STRUCTU 

RE  DosList, 0 

0 

$0 

BPTR 

dol_Next 

;next  entry 

4 

$4 

LONG 

dol_Type 

;type  (see  below) 

8 

$8 

APTR 

dol_Task 

; Handler  task 

12 

$c 

BPTR 

dol_Lock 

;Lock 

16 

$10 

LABEL 

dol_VolumeDate 

; creation  date 

16 

$10 

LABEL 

do l_As s  i gnName 

;path  name 

16 

$10 

BSTR 

dol_Handler 

; filename  (if  SegList=0) 

20 

$14 

LABEL 

dol_List 

.•directory  list  (Assign) 

20 

$14 

LONG 

dol_StackSize 

; stack  size  for  the  process 

24 

$18 

LONG 

dol_Priority 

,-priority  of  the  process 

28 

$1C 

LABEL 

dol_LockList 

;available  Locks 

28 

$1C 

ULONG 

dol_Startup 

; FileSysStartupMsg 

32 

$20 

LABEL 

dol_DiskType 

; ' DOS ' ,  etc . 

32 

$20 

BPTR 

dol_SegList 

;SegList  for  the  process 

36 

$24 

BPTR 

dol_GlobVec 

;BCPL  global  vector 

40 

$28 

BSTR 

dol_Name 

;name 

44 

$2C 

LABEL 

DosList_SIZEOF 

Values  for  dlType: 


DLT_DEVICE 

= 

0 

; logical  device 

DLT_DIRECTORY 

= 

1 

; As sign  Node 

DLT_VOLUME 

= 

2 

/diskette 

DLT_LATE 

= 

3 

; late  assignment 

DLT_NONBINDING 

= 

4 

;free  Assign  (AssignPath) 

DLT_PRIVATE 

= 

-1 

; for  DOS  only 

Flags  for  LockDosList()  etc.: 


LDB_READ 

LDB_WRITE 

LDB_DEVICES 

LDB_VOLUMES 

LDB_ASSIGNS 

LDB_ENTRY 

LDB_DELETE 


=  0,  LDF_READ 


=   1 


1,  LDF_WRITE    =   2 

2,  LDF_DEVICES  =   4 

3,  LDF_VOLUMES  =   8 

4,  LDF_ASSIGNS  =16 

5,  LDF_ENTRY    =32 

6,  LDF_DELETE   =64 


specify  either  LDF_READ 
or  LDF_WRITE 


; for  internal  purposes 


LDF_ALL  =  (LDF_DEVICES!LDF_VOLUMES!LDF_ASSIGNS) 
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3.  Handlers  and  Filesy stems 

|  AddBuffers  Add  to  the  number  of  buffers  for  a  device  | 

Call:  success  =  AddBuffers (filesystem,    number) 

DO  -732 (A6)        Dl  D2 

BOOL  success 
APTR  filesystem 
LONG  number 

Function:  Adds  the  given  number  of  buffers  to  the  existing  number  of 
buffers  for  a  filesystem,  then  sets  the  number  of  buffers  to 
the  new  number.  You  may  also  use  negative  values.  If  the 
call  was  successful,  you  can  query  the  current  number  of 
buffers  with  IoErr(). 

Parameters:  filesystem    *String  with  the  device  name,  including ':'. 

number       Number  of  buffers  to  add  (may  be  positive  or 
negative). 

Result:  0  Error 

See  also:       IoErr() 

[DeviceProc  Return  the  MsgPort  for  the  handler  of  a  device  I 

Call:  process  =  DeviceProc  (  name   ) 

DO  -174 (A6)  Dl 

STRUCT  MsgPort   *process 
APTR       name 

Function:  Returns  the  MessagePort  that  controls  the  given  device. 
This  is  required  for  packet  routines. 

Parameters:  name  Device  name 

Result:  MsgPort  of  the  handler  process  or  0. 
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Warning:  If  you  specify  something  that  is  only  addressable  as  a 
device  via  ASSIGN,  use  the  IoErr()  function  to  get  the  lock 
associated  with  this  name.  You  may  only  work  with  a  copy 
of  the  lock  that  was  created  with  DupLock(). 

See  also:       DoPkt(),  IoErr(),  DupLock() 

1  DoPkt  Send  a  DOS  packet  and  wait  for  the  reply] 

Call:  resultl    (/result2)    =  DoPkt(port,action,argl,arg2,arg3,arg4,arg5) 

DO  (Dl)  -240(A6)    Dl   D2  D3        D4        D5        D6        D7 

LONG      resultl, result2 

STRUCT  MsgPort  *port 

LONG       action, argl ,  arg2 , arg3 , arg4 , arg5 

Function:  PutMsgO  sends  a  packet  to  the  ProcessPort  of  the  handler 
and  waits  for  the  handler  to  process  it.  Then  resultl  and 
result2  are  taken  from  the  returned  packet.  Since  C 
programmers  cannot  use  routines  with  two  results,  result2  is 
set  up  as  an  error  code  that  can  be  queried  with  IoErr(). 

DoPkt()  can  also  be  called  by  an  Exec  task,  but  it  will  be 
slower  and  more  prone  to  error. 

Parameters:  port  pr_MsgPort  of  the  handler. 

action         Command  for  the  handler  or  filesystem. 

argl,  arg2,  arg3,  arg4,arg5 

Arguments  for  the  command. 

Result:  0  in  DO  =  error 

See  also:       DeviceProc(),  IoErr(),  PutMsgO,  WaitPort(),  GetMsgO 

lEndNotity  End  file  notification! 


Call:  EndNotify  (notifystructure) 

-894 (A6)   Dl 

STRUCT  NotifyRequest  *notifystructure 
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Function:      Ends  notification  started  with  StartNotify(). 
Parameters:  NotifyRequest  that  was  passed  to  StartNotify(). 
Result:  None 

See  also:       StartNotifyO 
| Format  Format  a  device | 

Call:  success  =  Format  (filesystem,  volumename,  dostype) 

DO        -714 (A6)  Dl        D2  D3 

BOOL   success 

APTR   filesystem, volumename 

ULONG  dostype 

Function:      Format  a  device,  such  as  a  diskette  or  a  hard  disk. 

Parameters:  filesystem    Device  name  including ':'. 

volumename 

Name,  such  as  the  diskette  name. 

dostype      Format  type:  OFS  or  FFS 

Result:  0  Error 

FreeDeviceProc      Free  a  structure  obtained  with  GetDeviceProcQI 


Call:  FreeDeviceProc  (devproc) 

-648 (A6)  Dl 

STRUCT  DevProc   *devproc 

Function:      Frees  a  structure  created  with  GetDeviceProc()  and 
decrements  the  process  counter. 

Parameters:  devproc      DevProc  structure  from  GetDeviceProcQ. 
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IGetConsoleTask 


Get  the  MsgPort  of  the  console  handler 


Call:  port  =  GetConsoleTaskO 

DO  -510 (A6) 

STRUCT  MsgPort   *port 

Function:      Returns  its  own  console  task  port  (pr_ConsoleTask). 

Result:  pr_MsgPort  of  the  console  handler  or  0. 

|  GetDeviceProc  Get  the  handler  for  a  path  | 

Call:  devproc  =  GetDeviceProc (name,    devproc) 

DO  -642 (A6)  Dl  D2 

STRUCT  DevProc   *devproc 
APTR       name 

Function:  Returns  the  handler  or  filesystem  for  a  path.  You  must 
supply  the  path  name,  which  may  be  given  relative  to  the 
current  path,  and  a  value  of  0  as  the  DevProc  structure.  The 
result  is  a  DevProc  structure  from  which  the  data  can  be 
read.  Kickstart  2.0  supports  the  division  of  a  directory  into 
several  devices,  so  more  than  one  handler/filesystem  may  be 
responsible  for  the  path. 

To  get  all  of  the  data  for  a  path,  GetDeviceProc()  must  be 
called  several  times,  and  the  first  structure  returned  must  be 
passed  with  each  subsequent  call.  If  you  receive  an 
ERROR_OBJECT_NOT_FOUND  and  if  DVPF.ASSIGN  is 
set  in  dvp_Flags,  you  must  still  call  this  function  again.  You 
will  receive  the  DevProc  structure  with  other  values  or  with 
the  value  0  and  an  ERROR_NO_MORE_ENTRIES  from 
IoErr().  The  function  must  continue  to  be  called  until  0  is 
returned.  Then  the  handler/filesystem  will  automatically  be 
locked.  The  structure  returned  with  the  first  call  can  be 
freed  with  FreeDeviceProc.  At  this  point,  all  of  the  data 
retrieved  becomes  invalid  and  must  not  be  used  anymore. 


Parameters:  name 


Path  name  to  be  accessed. 
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Result: 


IGetFileSysTasit 


devproc      DevProc  structure  from  previous  call,  or  0. 
DevProc  structure  or  null 

Get  MsgPort  of  own  filesystem] 


Call:  port  =  GetFileSysTaskO 

DO  -522 (A6) 

STRUCT  MsgPort   *port 

Function:     Reads  the  MsgPort  of  the  filesystem  from  the  process 
structure  responsible  for  the  program  (pr_FileSystemTask). 

Result:  pr_MsgPort  of  the  filesystem  or  0. 

Send  the  DOS  packet  ACTION  INHIBIT  to  a  handler] 


|  Inhibit 

Call: 


success  =  Inhibit (filesystem,  flag) 
DO        -72  6 (A6)  Dl  D2 


BOOL  success 
APTR  name 
LONG  flag 

Function:  Simultaneous  access  to  a  filesystem  device  must  be  locked 
before  direct  access  is  allowed  (Workbench:  DFx:BUSY). 
Programmers  who  simply  jump  in  and  access  the  trackdisk 
device  or  the  hard  disk  already  had  many  system  crashes 
and  instances  of  destroyed  data.  Normally,  you  would  use 
DeviceProcO  to  get  the  handler  port  and  then  turn  the 
filesystem  off  with  an  ACTIONJNHIBIT  packet.  This 
function  was  implemented  to  give  programmers  a  way  to 
accomplish  this. 

Parameters:  filesystem    Device  name  including ':' 

flag  Argument  for  the  StdPacket: 

DOSTRUE     Inhibit  (lock  filesystem) 
Null  Uninhibit  (unlock  filesystem) 
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Result: 


Error 


lIsFileSystem 


Determine  if  a  handler  is  a  filesystem| 


Call:  result   =  IsFileSystem(name) 

DO  -708 (A6)  Dl 

BOOL  Result:        APTR  name 

Function:     Returns  a  boolean  argument  that  indicates  whether  a 
handler  is  a  filesystem. 

Parameters:  name  Device  name  including ':'. 

Result:  0  Handler  is  not  a  filesystem. 


|  Relabel 


Change  name  of  a  storage  device  | 


Call: 


Function: 
Parameters: 

Result: 


success  =  Relabel (volumename, name) 
DO        -720 (A6)  Dl        D2 

BOOL  success 

APTR  volumename, name 

Changes  the  name  of  a  storage  device,  such  as  a  diskette. 

volumename  Device  name  including ':'. 

newname    New  name  without ':'. 


0 


Error 


IReplyPkt 


Reply  to  a  DosPacket| 


Call:  ReplyPkt  (packet,    resultl,    result2) 

-258 (A6)    Dl  D2  D3 

STRUCT  DosPacket   *packet 
LONG  resultl, result2 

Function:     Places  results  in  a  packet  and  returns  it  to  the  sender. 
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Parameters:  packet         DosPacket  structure. 

resultl  ,result2 

Results 

|  SendPkt  Send  a  DosPacket  to  a  handler  I 

Call:  SendPkt  (port,  packet,  replyport) 

-246 (A6)  Dl    D2        D3 

STRUCT  MsgPort  *port,  *replyport 
STRUCT  DosPacket  *packet 

Function:  Sends  a  packet  to  a  handler  without  waiting  for  the  reply. 
The  reply  is  sent  to  the  specified  ReplyPort.  This  is  the 
pr_MsgPort  of  its  own  process  structure. 

Parameters:  port  pr_MsgPort  of  the  handler  (see  DeviceProcO). 

packet  DosPacket  structure  to  be  sent. 

replyport  pr_MsgPort  of  its  own  process. 

ISetConsoleTask  Set  console  handler  port| 

Call:  oldPort  =  SetConsoleTask(port) 

DO  -516 (A6)  Dl 

STRUCT  MsgPort   *port,    *OldPort 

Function:  Sets  the  port  for  the  standard  console  tasks  of  the 
processor  (pr_ConsoleTask). 

Parameters:  port  pr_MsgPort  of  the  console  handler. 

Result:  Pointer  to  previous  console  task. 
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|  SetFileSysTask  Set  filesystem  port  | 

Call:  oldPort  =  SetFileSysTask  (port) 

DO         -528 (A6)        Dl 

STRUCT  MsgPort  *port,  *OldPort 

Function:  Sets  the  port  for  the  filesystem  tasks  of  the  process 
(prJFileSystemTask). 

Parameters:  port  pr_MsgPort  of  the  filesystem. 

Result:  Previous  FileSysTask 

|  StartNotify  Start  file  notification  | 

Call:  success  =  StartNotify  (notifystructure) 

DO         -888 (A6)     Dl 

BOOL   success 

STRUCT  NotifyRequest  *notifystructure 

Function:  Begin  notification  for  a  file  or  directory.  You  are  then 
notified  if  a  change  is  made,  as  long  as  the  filesystem 
supports  this. 

Parameters:  notifystructure 

Initialized  NotifyRequest  structure. 

Result:  0  Error 

|  WaitPkt  Wait  for  a  DosPacket  | 

Call:  packet  =  WaitPktO 

DO  -252 (A6) 

STRUCT  DosPacket   *packet 

Function:  Waits  for  a  DosPacket  to  appear  in  its  own  pr_MsgPort  and 
picks  up  the  StdPkt  with  GetMsg(). 
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Result:  packet        DosPacket    (LN_NAME    of   the    message 

structure) 

DosPacket  Structure: 


Dec 

Hex 

STRUCTURE  DosPacket, 0 

0 

$0 

APTR 

dp_Link 

-Exec  message 

4 

$4 

APTR 

dp_Port 

•Reply Port 

8 

$8 

LABEL 

dp_Action 

s.  ACTION...  .  . 

8 

$8 

LONG 

dp_Type 

'R',  'W 

12 

$C 

LABEL 

dp_Status 

1st  result: 

12 

$c 

LONG 

dp_Resl 

1st  result 

16 

$10 

LABEL 

dp_Status2 

2nd  result 

16 

$10 

LONG 

dp_Res2 

2nd  result 

20 

$14 

LABEL 

dp_BufAddr 

buffer  address 

20 

$14 

LONG 

dp_Argl 

1st  argument 

24 

$18 

LONG 

dp_Arg2 

2nd  argument 

28 

$1C 

LONG 

dp_Arg3 

3rd  argument 

32 

$20 

LONG 

dp_Arg4 

4th  argument 

36 

$24 

LONG 

dp_Arg5 

5th  argument 

40 

$28 

LONG 

dp_Arg6 

6th  argument 

44 

$2C 

LONG 

dp_Arg7 

7th  argument 

48 

$30 

LABEL 

dp_SIZEOF 

Structure  for  sending  Packets: 


Dec  Hex  STRUCTURE  StandardPacket , 0 

0   $0  STRUCT  sp_Msg,MN_SIZE    ;Exec  message 
20  $14  STRUCT  sp_Pkt, dp_SIZEOF  ; Packet 

68  $44  LABEL   sp_SIZEOF 


Packet  Types: 

ACTION_NIL 

= 

0 

;no  message 

ACTION_STARTUP 

= 

0 

; Handler  startup 

ACTION_GET_BLOCK 

= 

2 

;DO  NOT  USE! 

ACTION_SET_MAP 

= 

4 

;set  map 

ACTION_DIE 

= 

5 

;end  process 

ACTION_EVENT 

= 

6 

; event 

ACTION_CURRENT_VOLUME 

= 

7 

; current  disk 

ACTION_LOCATE_OBJECT 

= 

8 

;find  object 

ACTION_RENAME_DISK 

= 

9 

;rename  disk 

ACTION_WRITE 

= 

■w 

; write 

ACTION_READ 

= 

'R' 

;  read 

ACTION_FREE_LOCK 

= 

15 

; free  Lock 

ACTION_DELETE_OBJECT 

= 

16 

; delete  object 

ACTION_RENAME_OBJECT 

= 

17 

/rename  object 
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ACTION_MORE_CACHE 

= 

18 

ACTION_COPY_DIR 

= 

19 

ACTION_WAIT_CHAR 

= 

20 

ACTION_SET_PROTECT 

= 

21 

ACTION_CREATE_DIR 

= 

22 

ACTION_EXAMINE_OBJECT 

= 

23 

ACTION_EXAMINE_NEXT 

= 

24 

ACTION_DISK_INFO 

= 

25 

ACTION_INFO 

= 

26 

ACTION_FLUSH 

= 

27 

ACTION_SET_COMMENT 

= 

28 

ACTION_PARENT 

= 

29 

ACTION_TIMER 

= 

30 

ACTION_INHIBIT 

= 

31 

ACTION_DISK_TYPE 

= 

32 

ACTION_DISK_CHANGE 

= 

33 

ACTION_SET_DATE 

= 

34 

ACTION_SAME_LOCK 

= 

40 

ACTION_SCREEN_MODE 

= 

994 

ACTION_READ_RETURN 

= 

1001 

ACTION_WRITE_RETURN 

= 

1002 

ACTION_SEEK 

= 

1008 

ACTION_FINDUPDATE 

= 

1004 

ACTION_FIND INPUT 

= 

1005 

ACTION_FINDOUTPUT 

= 

1006 

ACTION_END 

= 

1007 

ACTION_FORMAT 

= 

1020 

ACTION_MAKE_LINK 

= 

1021 

ACTION_SET_FILE_SIZE 

= 

1022 

ACTION_WRITE_PROTECT 

= 

1023 

ACTION_READ_LINK 

= 

1024 

ACTION_FH_FROM_LOCK 

= 

1026 

ACTION_IS_FILESYSTEM 

= 

1027 

ACTION_CHANGE_MODE 

= 

1028 

ACTION_COPY_DIR_FH 

= 

1030 

ACTION_PARENT_FH 

= 

1031 

ACTION_EXAMINE_ALL 

= 

1033 

ACTION_EXAMINE_FH 

= 

1034 

ACTION_LOCK_RECORD 

= 

2008 

ACTION_FREE_RECORD 

= 

2009 

ACTION_ADD_NOTIFY 

= 

4097 

ACTION_REMOVE_NOTIFY 

= 

4098 

add  buffer 

copy  directory 

wait  for  a  character 

set  protection 

create  directory 

examine  object 

examine  next  entry 

info  on  the  disk 

information 

invalid  buffers 

set  comment 

parent  directory 

Timer  event 

Handler  on/off 

diskette  type 

diskette  change 

set  date 

compare  Locks 

screen  mode 

read 

write 

position 

open 

old  file 

new  file 

end 

format 

create  a  link 

set  file  size 

write  protect 

read  link 

get  FileHandle 

get  Handler  type 

change  access  mode 

copy  directory 

get  parent  directory 

examine  directory  tree  structure 

examine  file 

lock  record 

free  record 

start  notification 

end  notification 


Packet  types  from  runlnewclil execute! system  to  the  Shell: 


RUN_EXECUTE  =  -1 
RUN_SYSTEM  =  -2 
RUN_SYSTEM_ASYNCH  =  -3 
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Results  of  GetDeviceProc(): 


Dec  Hex  STRUCTURE  DevProc , 0 

0   $0  APTR    dvp_Port  ;MsgPort 

4   $4  BPTR    dvp_Lock  ;Lock 

8   $8  ULONG   dvp_Flags  ; Flags  (s.u.) 

12   $C  APTR     dvp_DevNode  ;DosList  (DO  NOT  USE!) 

16  $10  LABEL    dvp_SIZEOF 


Values  for  dvp_Flags 


DVPB_UNLOCK 
DVPB_ASSIGN 


0,  DVPF_UNLOCK  =  1 

1,  DVPF_ASSIGN  =  2 


Storage  device  description: 


)ec 

Hex 

0 

$0 

4 

$4 

8 

$8 

12 

$c 

16 

$10 

20 

$14 

24 

$18 

28 

$1C 

32 

$20 

36 

$24 

40 

$28 

44 

$2C 

48 

$30 

52 

$34 

56 

$38 

60 

$3C 

64 

$40 

68 

$44 

72 

$48 

76 

$4C 

80  $50 


STRUCTURE  DosEnvec.O 
ULONG  deJTableSize 
ULONG  de_SizeBlock 
ULONG  de_SecOrg 
ULONG  de_Surfaces 
ULONG  de_SectorPerBlock 
ULONG  de_BlocksPerTrack 
ULONG  de_Re served 
ULONG  de_PreAlloc 
ULONG  de_Interleave 
ULONG  de_LowCyl 
ULONG  de_HighCyl 
ULONG  de_NumBuffers 
ULONG  de_BufMemType 
ULONG  de_MaxTransfer 
ULONG  de_Mask 
LONG  de_BootPri 
ULONG  de_DosType 
ULONG  de_Baud 
ULONG  de_Control 
ULONG  de_BootBlocks 
LABEL  DosEnvec_SIZEOF 


table  size 

block  size  in  Longs 

sector  organization  (0) 

number  of  heads 

sectors  per  block  (1) 

blocks  per  track 

reserved  blocks  at  the  beginning 

reserved  blocks  at  the  end 

interleave  mode  (0) 

first  cylinder  (starting  with  0) 

last  cylinder 

normal  buffer  count 

memory  type  of  buffer 

maximum  speed 

address  mask 

boot  priority 

DOS  type 

baud  rate  for  serial  Handlers 

control  Word  for  Handler 

number  of  boot  blocks 


Filesystem  startup  message: 

Dec  Hex  STRUCTURE  FileSysStartupMsg, 0 

0   $0  ULONG   fssm_Unit    ;unit  number  for  OpenDeviceO 

4   $4  BSTR    fssm_Device   ;DeviceName  ending  in  0 

8   $8  BPTR    fssm_Environ  ; structure  of  data  storage  device 

12   $C  ULONG   fssm_Flags    ; Flags  for  OpenDeviceO 

16  $10  LABEL   FileSysStartupMsg_SIZEOF 
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NOTIFY_CLASS  =  $40000000 
NOTIFY_CODE   =  $1234 


;this  will  change. 
;this  too 


Dec  Hex  STRUCTURE  NotifyMessage, 0 

0   $0  STRUCT  nm_ExecMessage,MN_SIZE  ;message 
20  $14  ULONG  nm_Class  ;s.o. 


24 

$18 

UWORD 

nm_Code 

;s.o. 

26 

$1A 

APTR 

nm_NReq 

; Notify  request  (do 

30 

$1E 

ULONG 

nm_DoNotTouch 

34 

$22 

ULONG 

nm_DoNotTouch2 

38 

$26 

LABEL 

NotifyMessage_SIZEOF 

Dec 

Hex 

STRUCTURE  NotifyRequest 

0 

0 

$0 

CPTR 

nr_Name 

;  Name 

4 

$4 

CPTR 

nr_FullName 

; complete  DOS  path 

8 

$8 

ULONG 

nr_UserData 

;own  data 

12 

$C 

ULONG 

nr_Flags 

; Flags 

16 

$10 

LABEL 

nr_Task 

;task  for  SEND_SIGNAL  or 

16 

$10 

APTR 

nr_Port 

;MsgPqrt  for  SEND_MESSAGE 

20 

$14 

UBYTE 

nr_S  igna  INum 

;for  SEND_SIGNAL 

21 

$15 

STRUCT 

nr_pad, 3 

24 

$18 

STRUCT 

nr_Reserved, 4*4 

40 

$28 

ULONG 

nr_MsgCount 

; number  of  Msgs  sent 

44 

$2C 

APTR 

nr_Handler 

; Handler  for  EndNotifyO 

48 

$30 

LABEL 

NotifyRequest_SIZEOF 

Values  for  nr_Flags: 


NRB_SEND_MESSAGE  =   0 , 

NRB_SEND_SIGNAL  =   1, 

NRB_WAIT_REPLY  =   3 , 

NRB_NOTIFY_INITIAL  =   4, 

NRB_MAGIC  =31, 


NRF_SEND_MESSAGE 

NRF_SEND_SIGNAL 

NRF_WAIT_REPLY 

NRF_NOTIFY_INITIAL 

NRF_MAGIC 

NR_HANDLER_FLAGS 


1 

2 

8 

16 

$80000000 

$ffff0000 


4.  Directories 


CreateDir 


Create  a  new  directory  | 


Call:  lock  =  CreateDir  (  name  ) 

DO      -120 (A6)    Dl 

BPTR  lock 
APTR  name 
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Function:      Creates  a  new  directory  and  returns  a  lock  for  it. 
Parameters:  name  String  containing  directory  name. 

Result:  BCPL  pointer  to  a  lock  or  0. 

See  also:       UnLockQ 


ICurrentDir 


Set  the  current  directory  | 


Call:  oldLock  =  CurrentDir  (  lock  ) 

DO         -126 (A6)     Dl 


BPTR  oldLock 
BPTR  lock 


Function: 


CurrentDirO  sets  the  directory  that  all  path  specifications 
will  use  as  a  starting  point.  You  are  required  to  pass  a  lock 
for  the  desired  directory.  As  a  result,  you  receive  the  lock  to 
the  directory  that  was  formerly  current. 


Parameters: 
Result: 

See  also: 
|ExAH 


lock 


BCPL  pointer  to  a  lock. 


BCPL  pointer  to  the  previous  current  directory.  A  value  of 
0  represents  the  boot  directory  that  is  set  by  a  reboot. 

Lock(),  UnLock() 

Examine  an  entire  directory  1 


Call:  continue  =  ExAll(lock,  buffer,  size,  type,  control) 

DO         -432 (A6)  Dl   D2       D3     D4     D5 


Function: 


BOOL  continue 

BPTR  lock 

APTR  buffer 

LONG  size, type 

STRUCT  ExAllControl  *control 

Examines  a  directory  and  fills  a  buffer  with  ExAllData 
structures. 
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Parameters:  lock 
buffer 
size 
type 


control 


Result: 


Directory  lock 

Buffer  address 

Buffer  size 

The  amount  of  data  that  will  be  stored  in  each 
file  (ED_.„).  Higher  values  contains  smaller 
values.  The  order  is  name,  type,  size,  protection 
bits,  date,  comment. 

ExAllControl  structure,  must  be  created  with 
AllocDosObject().  The  LastKey  entry  must  be 
deleted  before  the  call.  If  several  calls  are 
required,  this  entry  may  not  be  changed. 

Entries  Number  of  entries  in  buffer. 

LastKey  Delete  prior  to  call. 

MatchString       Optional  pattern  string. 

MatchFunc         Hook  address  of  a  pattern 
matching  routine. 

Cancel  (delete  LastKey): 

IoErrQ 


ERROR_NO_MORE_ENTRIES: 
ExAll    is   finished;    otherwise 
IoErr()=error  code.  In  any  other 
case*  save  the  buffer  contents  and 
call  ExAllQ  again. 


See  also:       IoErrQ,  AllocDosObject(),  FreeDosObject 


I  Examine 


Examine  directory  or  file| 


Call:  success  =  Examine  (   lock,    infoBlock  ) 

DO  -102  (A6)    Dl  D2 


BOOL  success 
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BPTR  lock 

STRUCT  FilelnfoBlock  *infoBlock 

Function:  ExamineQ  fills  a  FilelnfoBlock  with  all  available 
information.  This  data  structure  can  only  be  read  if  it's 
passed  as  a  parameter  later  (e.g.,  to  ExNextO). 

Parameters:  lock  Lock  for  the  file/directory  to  be  examined. 

infoBlock   Address  of  FilelnfoBlock  structure. 

Result:  0  Error 


|ExNext 


Examine  next  directory  entry 


Call:  success  =  ExNext  (    lock,    infoBlock   ) 

DO  -108 (A6)    Dl        D2 

BOOL        success 

BPTR        lock 

STRUCT  FilelnfoBlock  *infoBlock) 

Function:  This  function  examines  the  next  directory  entry  and  fills  the 
fields  of  the  given  FilelnfoBlock  with  the  values  that  were 
obtained.  Prior  to  the  first  call,  the  FilelnfoBlock  must  be 
initialized  with  the  Examine()  function. 


Parameters:  lock 


Lock  for  the  directory  being  examined.  This 
lock  must  correspond  with  the  lock  from  the 
Examine()  call.  File  locks  do  not  work. 


infoBlock    Address  of  FilelnfoBlock  structure  that  was 
initialized  by  Examine(). 


Result: 


0 


If  IoErr()=ERROR_NO_MORE_ENTRIES, 
then  no  more  entries  are  available.  Otherwise, 
IoErrQ  returns  the  error  number. 


Warning:  Recursive  reading  of  the  directory  tree  structure  will  only 
work  if  you  use  a  new  FilelnfoBlock  for  each  directory 
found. 
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IGetProgramDir  Get  directory  lock  for  the  program | 

Call:  lock  =  GetProgramDir  ( ) 

DO  -600 (A6) 

BPTR   lock 

Function:  Returns  a  lock  for  the  directory  from  which  the  program  is 
started.  You  can  make  a  working  copy  of  this  lock  with 
DupLock(). 

Result:  Lock  or  0  (for  example,  in  the  case  of  a  resident  program) 

I  Info  Get  information  about  a  disk  | 

Call:  success  =  lnfo(  lock,  parameterBlock  ) 

DO       -114 (A6)  Dl    D2 

BOOL   success 

BPTR    lock 

STRUCT  InfoData  *parameterBlock 

Function:  Fills  the  InfoData  structure  with  information  on  the  disk 
that  corresponds  to  a  given  lock. 

Parameters:  lock  A  filesystem  lock 

parameterBlock 

InfoData  structure 

Result:  0  Error 

MatchEnd  Free  MatchFirstQ/MatchNextQ  memory  | 


Call:  MatchEnd  (AnchorPath) 

-834 (A6)    Dl 

STRUCT  AnchorPath  *AnchorPath 

Function:     Free  pattern  matching  memory. 
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Parameters:  AnchorPath 

Structure  of  MatchFirst()/MatchNext(). 

|  MatchFirst  Find  a  file  that  matches  the  pattern] 

Call:  error  =  MatchFirst  (pat,  AnchorPath) 

DO       -822 (A6)    Dl    D2 

BOOL  error 

APTR  pat 

STRUCT  AnchorPath  *AnchorPath 

Function:  Finds  the  first  file  or  directory  that  matches  the  given 
pattern.  Initializes  the  AnchorPath  structure.  Possible 
characters  in  the  pattern  string  are: 

?  Individual  character 

#  0  or  more  characters 

(alb)  Individually  check  components  separated  by  I 

~  Exclude  the  following  expression 

[abc]  One  of  the  specified  characters 

[a-z]  Range  of  characters,  such  as  "[0-9a-zA-Z]" 

%  No  character  (useful  with  "(albl%)") 

*  Can  optionally  be  used  for  "#?" 

Parameters:  pat  Pattern  string 

AnchorPath 

Structure  for  the  search. 

Result:  0  Okay,  otherwise  error  code. 

|  MatchNext  Find  next  file  that  matches  the  pattern  | 

Call:  error  =  MatchNext  (AnchorPath) 

DO  -828 (A6)       Dl 

BOOL        error 

STRUCT  AnchorPath  *AnchorPath 

Function:  Finds  the  next  file  or  directory  to  match  the  given  pattern 
(see  MatchFirst()). 
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Parameters:  AnchorPath 

MatchFirst()  structure 

Result:  0  Okay,  otherwise  error  code. 


ParentDir  Get  parent  directory  lock| 


Call:  newlock  =  ParentDir  (    lock   ) 

DO  -210 (A6)         Dl 

BPTR  newlock, lock 

Function:      Returns  a  lock  for  the  parent  directory  of  a  file  or  directory. 

Parameters:  lock  BCPL  pointer  to  a  lock  structure. 

Result:  Lock  or  0  (=  boot  directory,  parent  directory  of  all  root 

directories) 

[ParentOfFH  Get  lock  for  a  file's  parent  directory  | 

Call:  lock  =  ParentOfFH  (fh) 

DO  -384 (A6)         Dl 

BPTR   lock.fh 

Function:      Returns  a  lock  for  the  parent  directory  when  given  a 
FileHandle. 

Parameters:  fh  FileHandle 

Result:  Lock  or  0  (error) 

Structure  ofExamine()  and  ExNextf): 

Dec  Hex  STRUCTURE  FilelnfoBlock, 0 

0  $0  LONG   fib_DiskKey  ; block  number  for  operating  system 

4  $4  LONG   fib_DirEntryType  ;type  of  entry  (<0:file,  >0 :directory) 

8  $8  STRUCT  fib_FileName,108  ; filename  ending  in  0 

116  $74  LONG   fib_Protection  ,-protection  status 

120  $78  LONG   fib_EntryType  ; f or  the  operating  system 

124  $7C  LONG   fib_Size  ;file  size  in  bytes 

128  $80  LONG   f ib_NumBlocks  ;file  size  in  blocks 
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132   $84  STRUCT  f ib_DateStamp, ds_SIZEOF  ; revision  date 

144   $90  STRUCT  f ib_Comment, 80  ; comment  ending  in  0 

224   $E0  STRUCT  f ib_Reserved, 3  6  ; reserved 

260  $104  LABEL   fib_SIZEOF 


Normal  values  for  fib_DirEntryType: 


ST_BOOT 

= 

0 

;boot  directory 

ST_ROOT 

= 

1 

;main  directory 

ST_USERDIR 

= 

2 

/directory 

ST_SOFTLINK 

= 

3 

;soft  link 

ST_LINKDIR 

= 

4 

;HardLink  to  directory 

ST_FILE 

= 

-3 

;file 

ST_LINKFILE 

= 

-4 

;HardLink  to  file 

FIBB. 
FIBF. 
FIBB. 
FIBF. 
FIBB. 
FIBF. 
FIBB. 
FIBF. 
FIBB. 
FIBF. 
FIBB. 
FIBF. 
FIBB. 
FIBF 


SCRIPT   = 
SCRIPT   = 
PURE 
PURE 

.ARCHIVE  = 
.ARCHIVE  = 
.READ     = 
READ 
.WRITE 
.WRITE 
.EXECUTE  = 
.EXECUTE  = 
DELETE   = 
DELETE   = 


6 

64 

5 

32 

4 

16 

3 

8 

2 

4 

1 

2 

0 

1 


Protection  status  bits: 

batch  file 

program  code  is  re-entrable 

(=RESIDENT-capable) 
deleted  when  file  is  changed 

disable  read  access 

disable  write  access 

disable  program  start 

disable  delete 

Values  for  ExAll(): 


ED_NAME 

ED_TYPE 

ED_SIZE 

ED_PROTECTION 

ED_DATE 

ED_COMMENT 


;name 

;name+type 

; name+type+length 

;name+type+length+protection 

;name+type+length+protection+date 

;name+type+length+protection+date+comment 


ExAll()  result  structure: 


Dec  Hex  STRUCTURE  ExAllData.O 

0   $0  APTR    ed_Next     ;next  ExAllData  structure 

4   $4  APTR    ed_Name      ;name 

8  $8  LONG    ed_Type     ;typ  or  end  of  structure 
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12  $C  ULONG 
16  $10  ULONG 
20  $14  ULONG 
24  $18  ULONG 
28  $1C  ULONG 
32  $20  APTR 


ed_Size 

ed_Prot 

ed_Days 

ed_Mins 

ed_Ticks 

ed_Comment 


;size  or  end  of  structure 
/protection  or  end  of  structure 
;date  stamp  or  end  of  structure 


/comment  or  end  of  structure 
?   ?  LABEL   ed_Strings   /strings  at  end  of  structure 

Control  structure  for  ExAll(): 

Dec  Hex  STRUCTURE  ExAllControl, 0 

0   $0  ULONG   eac_Entries      /number  of  buffer  entries 
4   $4  ULONG   eac_LastKey     /disk  block  (do  not  change) 
8   $8  APTR    eac_MatchString  /pattern  string  or  0 

12   $C  APTR    eac_MatchFunc   /pattern  match  Hook  or  0 

16  $10  LABEL    ExAllControl_SIZEOF 


Structure  oflnfoQ: 


Dec 

Hex 

0 

$0 

4 

$4 

8 

$8 

12 

$c 

16 

$10 

20 

$14 

24 

$18 

28 

$1C 

32 

$20 

36  $24 


STRUCTURE  InfoData, 0 
LONG  id_NumSoftErrors 
LONG  id_UnitNumber 
LONG  id_DiskState 
LONG  id_NumBlocks 
LONG  id_NumBlocksUsed 
LONG  id_BytesPerBlock 
LONG  id_DiskType 
BPTR  id_VolumeNode 
LONG  id_InUse 
LABEL  id_SIZEOF 


number  of  errors  on  disk 
number  for  OpenDevice 
diskette  status  (see  below) 
number  of  blocks  on  disk 
number  of  blocks  used 
bytes  per  block 
disk  type 

BPTR  to  DosList  structure 
Flag,  0=not  active 


ID_WRITE_PROTECTED 

ID_VALIDATING 

ID_VALIDATED 


Diskette  status: 

80  /write  protection  on 

81  /disk  being  checked 

82  /disk  is  okay 


Diskette  type: 


ID_NO_DISK_PRESENT 

= 

-1 

ID_UNREADABLE_DISK 

= 

•BAD'«8 

ID_NOT_REALLY_DOS 

= 

'NDOS' 

ID_DOS_DISK 

= 

'  DOS  •  «8 

ID_FFS_DISK 

= 

'  DOS '  «8 

ID_KICKSTART_DISK 

= 

' KICK ' 

ID_MSDOS_DISK 

= 

'MSD'«8 

/no  disk  in  drive 

/unreadable  format  or  error 

/unreadable  format 

,-OFS  disk 

/FFS  disk 

/operating  system  diskette 

/MS-DOS  diskette 
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Pattern  matching  structure: 


Dec 

0 

0 

4 

4 

8 

12 

16 

16 

17 

18 

20 

280 

280 


Hex 
$0 

$0 
$4 
$4 
$8 
$C 
$10 
$10 

$11 

$12 

$14 

$118 

$118 


STRUCTURE  Anchor Path, 0 

LABEL  ap_First 

CPTR  ap_Base 

LABEL  ap_Current 

CPTR  ap_Last 

LONG  ap_BreakBits 

LONG  ap_FoundBreak 

LABEL  ap_Length 

BYTE  ap_Flags 

BYTE  ap_Reserved 

WORD  ap_Strlen 

STRUCT  ap_Info,fib_SIZEOF 

LABEL  ap_Buf 

LABEL  ap_SIZEOF 


; first  Anchor 

; last  Anchor 
; break  bits 
; found  bits 

; Flags 

/string  length 
;FileInfoBlock 
.•buffer  for  path 


APB_DOWILD      =   0  ;OPT  ALL 

APF_DOWILD      =   1 

APB_1TSWILD    =   1  ;Flag  from  MatchFirstO  for  MatchNext ( 

APF_ITSWILD     =   2 

APB_DODIR      =  2  ; directory  must  also  be  checked 

APF_DODIR       =   4 

APB_DIDDIR     =   3  /directory  being  checked 

APF_DIDDIR      =   8 

APB_NOMEMERR   =  4  ;not  enough  memory 

APF_NOMEMERR    =16 

APB_DODOT      =  5  ; conversion  of  ■ . '  in  CurrentDir 

APF_DODOT       =32 

APB_DirChanged  =   6  ; directory  has  changed  since 

APF_DirChanged  =  64  ;last  MatchNext  call 

Anchor  structure: 


Dec 

Hex 

STRUCTURE   AChain, 0 

0 

$0 

CPTR 

an_Child 

4 

$4 

CPTR 

an_Parent 

8 

$8 

LONG 

an_Lock 

12 

$c 

STRUCT 

an_Info, f ib_SIZEOF 

272 

$110 

BYTE 

an_Flags 

273 

$111 

LABEL 

an_string 

273 

$111 

LABEL 

an_SIZEOF 

FilelnfoBlock 


DDB_PatternBit  =  0, 
DDB_ExaminedBit  =  1, 
DDB_Completed  =  2, 
DDB_AllBit  =  3, 
DDB_S INGLE       =  4, 


DDF_PatternBit  =  1 
DDF_ExaminedBit  =  2 
DDF_Completed  =  4 
DDF_AllBit  =  8 
DDF_SINGLE       =16 
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Tokens  for  Token  strings: 


P_ANY 

= 

$80 

Token  for  '*'  or  '#? 

P_S INGLE 

= 

$81 

Token  for  ' ? ' 

P_ORSTART 

= 

$82 

Token  for  ' ( ' 

P_ORNEXT 

= 

$83 

Token  for  ' 1 ' 

P_OREND 

= 

$84 

Token  for  ' ) ' 

P_NOT 

= 

$85 

Token  for  ' - ' 

p_NOTEND 

= 

$86 

end  of  expression  after  '-' 

PJTOTCLASS 

= 

$87 

Token  for  ' A ' 

P_CLASS 

= 

$88 

Token  for  ' ( ) ' 

P_REPBEG 

= 

$89 

•  Token  for  ' [ ' 

P_REPEND 

= 

$8A 

•  Token  for  ' ] ' 

P_STOP 

= 

$8B 

•  cancel  evaluation 

COMPLEX_BIT 
EXAMINE_BIT 


Values  for  an_Status: 

1  ;  pattern  parsing 

2  ;  search  in  directory 


5.  Programs 


lAddSegment 


Insert  program  in  resident  list] 


Call:  success  =  Adds egment (name,  seglist,  type) 

DO         -774  (A6)    Dl     D2       D3 

BOOL  success 
APTR  name 
BPTR  seglist 
LONG  type 

Function:     Inserts  a  program  in  the  resident  list  (to  hold  it  in  memory). 

Parameters:  name  Program  name 

seglist         BPTR  (APTR/4)  to  program's  segment  list 
type  Call  counter  for  linking,  normal  value:  0. 

Result:  0  Error 
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|  CreateNewProc  Generate  a  new  process | 

Call:  process  =  CreateNewProc  (tags) 

DO  -498 (A6)  Dl 

STRUCT  Process   *process 
STRUCT  Tagltem  *tags 

Function:  Generates  a  new  process  according  to  the  values  in  the  tag 
array.  NP_Seglist  or  NP_Entry  must  be  included. 
NP_Seglist  passes  a  BPTR  to  a  segment  list  and  NP_Entry 
passes  the  address  of  the  program.  Input  and  output  are 
routed  to  NIL:  and  the  stack  is  set  to  4000  bytes. 

CreateNewProc  can  be  called  from  a  simple  task,  but  in  this 
case  the  DOS  I/O  will  not  work. 

Parameters:  tags  Address  of  a  Tagltems  field. 

Result:  Process  or  0 

ICreateProc  Generate  a  new  process  (old) | 

Call:  process  =  CreateProc(  name,  pri,  seglist,  stackSize  ) 

DO        -138 (A6)     Dl    D2   D3       D4 

STRUCT  MsgPort  "process 
APTR  name 
LONG  pri 
BPTR  seglist 
LONG  stackSize 

Function:      CreateProc  starts  a  new  process  with  the  given  name. 

Parameters:  name  Address  of  the  string  with  the  process  name, 

pri  Priority  of  the  process  (-128  to  127) 

seglist         BPTR  to  a  SegList  (see  LoadSegO) 
stackSize    Stack  size  (multiple  of  4) 
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Result:  Process  or  0  (error) 

See  also:       LoadSegO,  CreateNewProc() 

|  Exit  End  BCPL  program  | 

Call:  Exit  (  returnCode   ) 

-144 (A6)    Dl 

LONG  returnCode 

Function:  Exit()  is  used  to  properly  end  BCPL  programs  only.  This 
routine  must  never  be  called  by  other  programs. 

Parameters:  returnCode 

Return  value  for  CLI. 

Result:  None. 

Warning:  C  programmers  must  be  careful  not  to  confuse  the  C 
function  exit()  with  the  DOS  function  Exit(). 

IFindSegment  Retrieve  a  segment  from  the  resident  listj 

Call:  segment  =  FindSegment (name,  start,  system) 

DO        -780  (A6)     Dl     D2      D3 

STRUCT  Segment  *segment, *start 
APTR   name 
LONG   system 

Function:  Finds  the  segment  of  the  given  name  in  the  list  of  resident 
programs.  You  can  also  specify  the  name  of  the  segment 
from  which  to  begin  the  search.  If  the  system  flag  is  set, 
then  only  one  system  segment  is  searched. 

Parameters:  name  Segment  name 

start  0  or  starting  segment  for  the  search 

system        0  or  - 1  for  system  segment 
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Result:  Segment  address  or  0 

Warning :      Turn  off  multitasking  before  calling. 
llnternalLoadSeg 


Load  program  from  FileHandle| 


Call: 


seglist  =  InternalLoadSeg(fh, table, functionarray, stack) 
DO        -756  (A6)        DO  AO    Al  A2 


BPTR  seglist, fh, table 
APTR  functionarray, stack 

Function:  Loads  the  program  represented  by  a  FileHandle.  If  no 
overlay  is  loaded,  then  table  must  be  set  to  0.  If  the  stack 
size  is  integrated  into  the  program,  then  it's  written  to  the 
address  given  in  stack.  There  may  already  be  a  value  stored 
at  this  address.  In  this  case,  it's  overwritten  by  the  loaded 
value. 

Parameters:  fh  FileHandle  of  the  program. 

table  Overlay  table  or  0 

functionarray 

Field  containing  addresses  of  three  functions: 

Actual      ReadFunc (readhandle, buf f er , length) , DOSBase 
DO  Dl  AO       DO       A6 

>   read  function,     normally  Read() 

Memory  =  AllocFunc (size, flags) , Execbase 
DO  DO    Dl      A6 

>  allocate  memory,  normally  AllocMem() 

FreeFunc (memory, size) , Execbase 
Al     DO      A6 
>  free  memory,  normally  FreeMemO 

stack  Variable  address  (LONG)  to  which  the  stack 

size  is  written. 

Result:  SegList  or  -(SegList)  for  overlays  or  0. 
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llnternalUnLoadSeg  Free  a  SegListl 

Call:  success  =  lnternalUnLoadSeg(seglist,FreeFunc) 

DO  -7  62 (A6)  Dl  Al 

BOOL  success 
BPTR  seglist 
FPTR  FreeFunc 

Function:  Frees  the  segments  of  a  SegList  and  closes  the  program  file 
for  overlays. 

Parameters:  seglist  SegList  of  a  program. 

FreeFunc  Free  function  (see  InternalLoadSegO) 

Result:  0  Error 

ILoadSeg  Load  program| 

Call:  seglist  =  LoadSeg(  name  ) 

DO         -150 (A6)  Dl 

BPTR  seglist 
APTR  name 

Function:  Loads  a  file  consisting  of  DOS  hunks  into  memory.  The 
memory  blocks  are  linked  with  BPTRs  in  the  first 
longword.  The  size  of  the  memory  block  precedes  the 
BPTR. 

Parameters:  name  Filename  (including  path) 

Result:  BPTR  to  the  first  segment  or  0. 

INewLoadSeg  Expanded  LoadSegQ  routine | 

Call:  seglist  =  NewLoadSeg(file,    tags) 

DO  -768 (A6)         Dl  D2 

BPTR       seglist 
APTR       file 
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STRUCT  Tagltem  *tags 

Function:      Loads  a  file  consisting  of  hunks,  depending  on  the  tags  in  a 
given  Tagltem  field. 

Parameters:  file  Filename 

tags  Address  of  a  Tagltem  field. 

Result:  Seglist  or  0 

[ RemSegment  Remove  a  program  from  the  resident  list| 

Call:  success   =  RemSegment  (segment) 

DO  -786 (A6)         Dl 

BOOL        success 

STRUCT  Segment   *segment 

Function:      Removes  a  resident  segment  from  the  system  list  and  frees 
the  allocated  memory. 

Parameters:  segment      Segment  structure 

Result:  0  Error  (usually  because  Usecount  is  not  0) 

|  RunCommand  Start  a  program  with  its  own  process  | 

Call:  re  =  RunCommand  (seglist,  stacksize,  argptr,  argsize) 

DO    -504  (A6)    Dl        D2  D3       D4 

LONG   re 

BPTR  seglist 

ULONG  argsize,  stacksize 

APTR  argptr 

Function:      Starts  a  program  using  its  own  process  structure. 
Parameters:  seglist         SegList  of  the  program, 
stacksize     Stack  size 
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argptr         Argument  string 

argsize        Length  of  argument  string 

Result:  Return  value  of  the  program  or  -1  if  the  stack  could  not  be 

loaded. 


lUnLoadSeg 


Free  SegList| 


Call:  success  =  unLoadSeg  (   seglist   ) 

DO  -156 (A6)         Dl 


NP_Dummy 

NP_Seglist 

NP_FreeSeglist 

NP_Entry 

NP_Input 

NP_Output 

NP_CloseInput 

NP_CloseOutput 

NP_Error 

NP_CloseError 

NP_CurrentDir 

NP_StackSize 

NP_Name 

NP_Priority 

NP_ConsoleTask 

NP_WindowPtr 

NP_HomeDir 

NP_CopyVars 

NP_Cli 

NP_Path 

NP_CommandName 

NP_Arguments 


BOOL  success 
BPTR   seglist 

Function:      Free  the  SegList  of  a  file  loaded  with  LoadSeg(). 

Parameters:  seglist         BCPL  to  a  SegList 

Result:  0  SegList  was  0  or  an  error  occurred. 

CreateNewProc()  Tags: 


TAG_USER+100 

NP_Dummy+l 

NP_Dummy+2 

NP_Dummy+3 

NP_Dummy+4 

NP_Dummy +  5 

NP_Dummy+6 

NP_Dummy+7 

NP_Dummy+8 

NP_Dummy+9 

NP_Dummy+10 

NP_Dummy + 1 1 

NP_Dummy+12 

NP_Dummy+13 

NP_Dummy+14 

NP_Dummy+15 

NP_Dummy+16 

NP_Dummy+17 

NP_Dummy+18 

NP_Dummy+19 

NP_Dummy+20 

NP_Dummy+21 


SegList  of  the  program 

free  SegList  at  end? 

program  address 

input  handle 

output  handle 

close (Inputhandle)  at  end? 

close (Outputhandle)  at  end? 

error  handle 

close (Errorhandle)  at  end? 

current  directory 

stack  size  in  bytes 

process  name 

process  priority 

Console  Handler 

window  for  Requester,  etc. 

start  directory 

copy  local  variables? 

create  CLI  structure? 

path  for  CLI 

program  name  for  CLI 

arguments  for  CLI 
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NP_NotifyOnDeath  =  NP_Dummy+22  /message  at  end? 

NP_Synchronous   =  NP_Dummy+23  ;wait  until  process  end? 

NP_ExitCode      =  NP_Dummy+24  ; routine  to  be  ended 

NP_ExitData      =  NP_Dummy+25  ;data  for  NP_EndCode 


Structure  of  a  process  (expanded  Task  structure): 


Dec 

Hex 

STRUCT! 

0 

$0 

STRUCT 

92 

$5C 

STRUCT 

126 

$7E  WORD 

128 

$80 

BPTR 

132 

$84 

LONG 

136 

$88 

APTR 

140 

$8C 

LONG 

144 

$90 

BPTR 

148 

$94 

LONG 

152 

$98 

BPTR 

156 

$9C 

BPTR 

160 

$A0 

BPTR 

164 

$A4 

APTR 

168 

$A8 

APTR 

172 

$AC 

BPTR 

176 

$B0 

APTR 

180 

$B4 

APTR 

184 

$B8 

APTR 

188 

$BC 

BPTR 

192 

$C0 

LONG 

196 

$C4 

APTR 

200 

$C8 

LONG 

204 

$CC  APTR 

208 

$D0 

STRUCT 

220 

$DC  APTR 

224 

$E0 

BPTR 

228 

$E4 

LABEL 

pr_Task, TC_SIZE 

pr_MsgPort , MP_SIZE 

pr_Pad 

pr_SegList 

pr_StackSize 

pr_GlobVec 

pr_TaskNum 

pr_StackBase 

pr_Result2 

pr_CurrentDir 

pr_CIS 

pr_COS 

pr_ConsoleTask 

pr_FileSystemTask 

pr_CLI 

pr_ReturnAddr 

pr_PktWait 

pr_WindowPtr 

pr_HomeDir 

pr_Flags 

pr_ExitCode 

pr_ExitData 

pr_Argument  s 

pr_LocalVars , MLH_SIZE 

pr_ShellPrivate 

pr_CES 

pr_SIZEOF 

pr_Flags  flags: 


;Task  structure 
; process  port 

SegList  of  the  program 

stack  size 

global  vector  (BCPL) 

CLI  process  number 

end  of  stack 

return  value 

Lock  for  current  directory 

input  channel 

output  channel 

pr_MsgPort  of  the  window  Handler 

pr_MsgPort  of  the  drive 

CLI  structure 

old  stack 

WaitPktO  function 

Requester  window 

start  directory 

Flags 

end  function 

data  for  the  function 

argument  string 

local  ENV  variables 

for  Shell  only 

error  channel,  in  case  pr_COS=0 


PRB_FREESEGLIST  =  0, 
PRB_FREECURRDIR  =  1, 
PRB_FREECLI  =  2, 
PRB_CLOSEINPUT  =  3, 
PRB_CLOSEOUTPUT  =  4, 
PRB_FREEARGS     =  5, 


PRF_FREESEGLIST  =  1 
PRF_FREECURRDIR  =  2 
PRF_FREECLI  =  4 
PRF_CLOSEINPUT  =  8 
PRF_CLOSEOUTPUT  =16 
PRF_FREEARGS     =32 
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Hunk  types: 


HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 


HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 
HUNK. 


.UNIT 

.NAME 

.CODE 

.DATA 

.BSS 

.RELOC32 

.RELOC16 

.RELOC8 

.EXT 

EXT_SYMB 
EXT_DEF 
EXT_ABS 
EXT_REF32 
EXT_COMMON 
EXT_REF16 
EXT_REF8 
EXT_DEXT32 
EXT_DEXT16 
EXT_DEXT8 

.SYMBOL 

.DEBUG 

_END 

.HEADER 

..OVERLAY 

_BREAK 

_DREL32 
DREL16 
DREL8 
LIB 
INDEX 


999 
1000 
1001 
1002 
1003 
1004 
1005 
1006 
1007 
0 

1 

2 
129 
130 
131 
132 
133 
134 
135 
1008 
1009 
1010 
1011 
1013 
;  1014 

:  1015 

:  1016 

:  1017 

:  1018 

:  1019 


part  of  an  object  code  file 

segment  name 

program  segment 

data  segment 

memory  block  (+MEMF_CLEAR) 

table  for  absolute  addressing 

offset  table 

offset  table 

linker  data 

symbol  table 

external  label 

absolute  value 

32  bit  symbol  reference 

32  bit  reference  to  global  data 

16  bit  symbol  reference 

8  bit  symbol  reference 

32  bit  relative  data  reference 

16  bit  relative  data  reference 

8  bit  relative  data  reference 

name  of  a  Long  value 

special  info  for  a  debugger 

end  of  main  segment 

info  on  the  following  Hunks 

overlay  Hunks 

end  of  Overlay 

relative  data  32  bit 

relative  data  16  bit 

relative  data  8  bit 

library 

table 


6.CU 


ICheckSignal 


Check  for  Cancel  signal  | 


Call:  signals  =  CheckSignal(mask) 

DO  -792 (a6)  Dl 

ULONG  signals 
ULONG  mask 

Function:  Tests  the  given  signal  bits.  The  signal  bits  are  masked  and 
passed  back.  All  bits  set  in  the  mask  are  reset  in  the  process 
structure. 
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Parameters:  mask 
Result:  signals 


Bit  mask  for  signal  bits. 

Logical  AND  combination  of  the  mask  and  the 
signal  bits. 


See  also:       exec.library/Signal 

fell 


(Jet  the  address  of  the  calling  CLII 


Call:  cli_ptr  =  Cli() 

DO  -492 (A6) 

STRUCT  CommandLinelnterface  *cli_ptr 

Function:      Returns  the  address  of  the  CLI  from  which  the  program 
was  started. 

Parameters:  None. 

Result:  Address  of  the  CLI  or  0  (Workbench). 

|  Execute 


Execute  CLI  command] 


Call:  success  =  Execute (  commandstring,  input,  output  ) 

DO         -222 (A6)  Dl  D2      D3 

BOOL  success 

APTR  commandStringExecute 

BPTR  input, output 


Function: 


Attempts  to  execute  a  CLI  command.  The  string  that 
contains  the  command  and  the  parameters  is  constructed 
exactly  as  it  would  be  if  entered  from  the  CLI  entry  line.  It 
can  contain  any  special  characters  available  to  CLI.  If  an 
input  channel  is  specified,  then  Execute()  will  read  further 
instructions  from  this  channel  after  the  execution  and 
change  the  process  in  the  case  of  an  interactive  channel  or 
a  re-routing  to  NIL:.  The  default  output  is  the  current 
window,  but  this  can  be  changed  by  specifying  a  different 
output  channel. 

Processes  are  started  using  the  RUN  command. 
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Parameters:  commandString 

Address  of  a  CLI  command  line. 

input  FileHandle 

output        FileHandle 

Result:  0  Error 

Warning:      Programs  started  from  the  Workbench  normally  do  not 
have  a  current  output  window. 

iFindCliProc  Find  a  CLI  process! 

Call:  proc  =  FindCliProc(num) 

DO  -546 (A6)  Dl 

STRUCT   Process   *proc 
LONG       num 

Function:      Returns  the  CLI  process  with  the  given  number. 

Parameters:  num  Task  number  of  the  CLI  process. 

Result:  Address  of  the  Process  structure  or  0  if  not  found. 

Warning:  To  be  safe,  this  routine  should  only  be  called  when 
multitasking  is  turned  off. 

| Input  Get  the  FileHandle  for  the  default  input  file] 

Call:  file  =   Input  0 

DO  -54 (A6) 

BPTR   file 

Function:  Returns  the  FileHandle  that  was  set  as  the  input  channel 
when  the  program  was  started.  This  FileHandle  may  not  be 
closed. 

Result:  Input  FileHandle  or  0 
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See  also: 
IMaxCii 


Output() 


tiet  the  highest  CLI  number  | 


Call:  number  =  MaxCli  ( ) 

DO       -552 (A6) 

LONG  number 

Function:  Returns  the  highest  process  number  of  all  the  CLI 
processes  running. 

Result:  Highest  CLI  process  number. 

Warning:  The  highest  process  number  does  not  necessarily  equal  the 
number  of  processes  currently  running,  since  processes 
with  lower  numbers  may  already  have  been  ended. 


|  Output 


Call:  file  =  Output  () 

DO     -60 (A6) 

BPTR  file 


Get  the  FileHandle  for  the  default  output  filel 


Function: 

Result: 
See  also: 
|ReadArgs" 


Returns  the  FileHandle  that  was  set  as  the  output  channel 
when  the  program  was  started.  This  FileHandle  may  not  be 
closed. 

Output  FileHandle  or  0 

InputQ 


Interpret  CLI  argument  string! 


Call:  result  =  ReadArgs (template,   array,    rdargs) 

DO  -798 (A6)    Dl  D2  D3 

STRUCT  RDArgs   *result , *rdargs 
APTR       template , array 
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Function:  Interprets  an  argument  string  using  a  pattern  string,  which 
can  contain  options  such  as  "Q=Quick".  Options  are 
separated  by  commas  in  the  pattern  string.  A  result  for  each 
option  is  expected  to  be  passed  in  the  longword  field. 
Options  can  be  defined  with  'f: 

/S  Switch,  BOOL,  0  =  not  given. 

/K  Keyword,  this  entry  is  only  filled  in  if  the 

keyword  was  found. 
/N  Number,  a  number  in  decimal  format. 

/T  Switch,  similar  to  /S. 

/A  Required  keyword. 

/F  Remainder  of  the  line. 

/M  Multiple  strings  (array  address  with  last 

string  address=0). 

The  RDArgs  structure  is  required  for  FreeArgs().  Such  a 
structure  is  normally  created  with  ReadArgs()  (parameter  = 
0). 

Parameters:  template      Input  format 

array  Longword  array  for  results 

rdargs         Optional  RDArgs  structure 

Result:  RDArgs  structure  or  0 

|  Readltem  Read  an  argument  from  an  argument  string  | 

Call:  value  =  Readltem (buffer,    maxchars,    input) 

DO  -810 (A6)    Dl  D2  D3 

LONG       value , maxchars 

APTR       buffer 

STRUCT  CHSource  * input 

Function:     Reads  a  word  or  a  character  string  enclosed  in  quotes  from 
Input()  or  a  CHSource  (if  given). 

Parameters:  buffer         Result  buffer 
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maxchars    Buffer  size 

input  CHSource  structure  or  0  (FGetC(Input())) 

Result:  See  data  structures. 

|  Selectlnput  Set  FileHandle  for  default  input  channel] 

Call:  old_fh  =  Selectlnput  (fh) 

DO  -294 (A6)  Dl 

BPTR  old_fh,fh 

Function:      Sets  the  value  that  Input()  returns  for  its  own  CLI  process. 

Parameters:  fh  New  InputHandle 

Result:  FileHandle  previously  returned  via  Input(). 

|  SelectOutput  Set  FileHandle  for  default  output  channel  | 

Call:  old_fh  =  SelectOutput  (fh) 

DO  -300 (A6)  Dl 

BPTR  old_fh,fh 

Function:      Sets  the  value  that  Output()  returns  for  its  own  CLI 

process. 

Parameters:  fh  New  OutputHandle 

Result:  FileHandle  previously  returned  by  Output(). 

|  Set ArgStr  Set  argument  string  | 

Call:  Oldptr  =  SetArgStr  (ptr) 

DO  -540 (A6)       Dl 

APTR  ptr,    Oldptr 

Function:      Sets  the  argument  string  for  the  running  process.  The  old 
string  must  be  restored  before  the  program  is  ended. 
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Parameters:  ptr  Address  of  new  argument  string. 

Result:  Oldptr         Address  of  old  string. 


SetCurrentDirName 

Sets  name  of  the  current  directory  in  the  process 


Call:  success  =  SetCurrentDirName  (name) 

DO  -558 (A6)  Dl 

BOOL  success 
APTR  name 

Function:      Manipulates  the  name  of  the  current  directory  within  the 
CLI  structure. 

Parameters:  name  New  directory  name 

Result:  0  Error 

|SetProgramDir  Sets  program  directory  | 

Call:  Oldlock  =  SetProgramDir  (lock) 

DO  -594 (A6)  Dl 

BPTR  lock,    Oldlock 

Function:      Sets  the  value  returned  by  GetProgramDir(). 

Parameters:  lock  Directory  lock 

Result:  Oldlock      Lock  on  previous  directory. 

|  SetProgramName  Set  program  name  | 

Call:  success  =  SetProgramName  (name) 

DO  -570 (A6)  Dl 

BOOL  success 
APTR  name 

Function:     Changes  the  program  name  in  the  CLI  structure. 
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Parameters:  name 
Result:  0 


Program  name 
Error 


SetPrompt 


Set  prompt  for  CLI/Sheli] 


Call:  success  =  SetPrompt  (name) 

DO  -582  (A6)       Dl 

BOOL  success 
APTR  name 

Function:      Sets  prompt  text  in  the  CLI  structure. 

Parameters:  name  Prompt  string 

Result:  0  Error 


ISystemTagLlsT 


Execute  command  from  Shell! 


Call:  error  =   SystemTagList (command,    tags) 

DO  -606 (A6)    Dl  D2 

LONG        error 
APTR       command 
STRUCT  Tagltem  *tags 

Function:      Similar  to   Execute(),   but  does   not  read   additional 
instructions  from  input  FileHandle. 

Parameters:  command    Shell  command  line 

tags  Tagltem  field  for  changes. 

Result:  Return  value  of  command  or  -1  (error). 

Output  a  formatted  string] 


IVPrintf 


Call:  count  =  VPrintf  (fmt,    argv) 

DO  -954 (A6)    Dl      D2 

LONG   count 
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APTR  f mt , argv [ ] 
Function:     Similar  to  VFPtrintf,  but  output  occurs  after  Output(). 
Parameters:  fmt  Format  string  for  exec/RawDoFmt(). 

argv  Field  containing  parameters. 

Result:  Number  of  output  bytes  or  -1  (error). 

Return  values  in  CLI: 

RETURN_OK    =  0  ; everything  okay 

RETURN_WARN  =   5  ;  warning 

RETURN_ERROR  =  10  ; error  occurred 

RETURN_FAIL   =  20  /complete  failure,  nothing  accomplished 

CU  Cancel  bits  (CONTROL  +  CIDIEIF) 

SIGBREAKB_CTRL_C  =  12,  SIGBREAKF_CTRL_C  =  $1000 

SIGBREAKB_CTRL_D  =  13,  SIGBREAKF_CTRL_D  =  $2000 

SIGBREAKB_CTRL_E  =  14,  SIGBREAKF_CTRL_E  =  $4000 

SIGBREAKB_CTRL_F  =  15,  SIGBREAKF_CTRL_F  =  $8000 

ReadltemO  values: 

ITEM_EQUAL    =  -2  ;"=■  Symbol 

ITEM_ERROR    =  -1  ; error 

ITEM_NOTHING  =   0  ;"*N",  ■ ; " ,  end 

ITEM_UNQUOTED  =   1  ;  no  quotes 

ITEM_QUOTED   =   2  ;with  quotes 

Readltem()  structure: 

Dec  Hex  STRUCTURE   CSource.O 
0   $0  APTR    CS_Buffer  ;buffer 
4  $4  LONG    CS_Length  ;buffer  size 
8   $8  LONG    CS_CurChr  ; current  character 
12   $C  LABEL    CS_SIZEOF 

ReadArgs()  structure: 

Dec  Hex  STRUCTURE   RDArgs,0 

0   $0  STRUCT  RDA_Source,CS_SIZEOF  ; source  string 
12   $C  APTR     RDA_DAList  ; PRIVATE 

16  $10  APTR    RDA_Buffer  .-buffer  (optional) 
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20  $14  LONG  RDA_BufSiz 

24  $18  APTR  RDA_ExtHelp 

28  $1C  LONG  RDA_Flags 

32  $20  LABEL  RDA_SIZEOF 


;buffer  size 
; optional  help 
; Flags 


RDA_Flags  values: 


RDAB_STDIN    =  0,  RDAF_STDIN    =  1  ;use  Stdln 
RDAB_NOALLOC   =  1,  RDAF_NOALLOC   =2  ;no  extra  buffer 
RDAB_NOPROMPT  =  2,  RDAF_NOPROMPT  =  4  ;no  input 

MAX_TEMPLATE_1TEMS  =  100  ;max.  number  of  arguments  (must  be  divisible  by  4!!!) 

MAX_MULTIARGS  =  128      ;max.  number  of  multiple  strings 

CLI  structure: 


Dec 

Hex 

STRUC 

0 

$0 

LONG 

4 

$4 

BSTR 

8 

$8 

BPTR 

12 

$C 

LONG 

16 

$10 

BSTR 

20 

$14 

LONG 

24 

$18 

BSTR 

28 

$1C 

BPTR 

32 

$20 

BPTR 

36 

$24 

BSTR 

40 

$28 

LONG 

44 

$2C 

LONG 

48 

$3  0 

BPTR 

52 

$34 

LONG 

56 

$38 

BPTR 

60 

$3C 

BPTR 

64 

$40 

LABEL 

STRUCTURE  CommandLinelnterface, 0 


cli_Result2 

cli_SetName 

c 1 i_CommandD i r 

c 1 i_ReturnCode 

c 1 i_CommandName 

cli_FailLevel 

cli_Prompt 

cli_StandardInput 

c 1 i_Cur r ent Input 

c 1 i_CommandF i 1 e 

cli_Interactive 

cli_Background 

cli_CurrentOutput 

cli_DefaultStack 

cli_StandardOutput 

cli_Module 

cli_SIZEOF 

SystemO  Tags: 


IoErr ( )  value 
current  directory 
command  directory 
return  value 
program  name 
error  level 
prompt  string 
default  input 
current  input 
batch  filename 
BOOL  if  terminal 
BOOL  if  RUN  command 
current  output 
stack  size  in  Longs 
default  output 
program's  SegList 


SYS_Dummy 

SYS_Input 

SYS_Output 

SYS_Asynch 

SYS_UserShell 

SYS_CustomShell 

SYS_Error 


TAG_USER+32 
SYS_Dummy+l 
SYS_Dummy+2 
SYS_Dummy+3 
SYS_Dummy+4 
SYS_Dummy+5 
SYS_Dummy+? 


;set  input  FileHandle 
;set  output  FileHandle 
; close  input/output 
;not  to  boot  Shell 
; specific  Shell  (name) 
.•anything  else  =  error 
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7.  Files 

[ChangeMode  Change  access  to  lock  or  FileHandle  | 

Call:  success  =  ChangeMode ( type ,    object,    newmode) 

DO  -450 (A6)         Dl  D2  D3 

BOOL     success 
ULONG  type 
bptr     object 
ULONG  newmode 

Function:      Changes  the  access  mode  for  a  lock  or  FileHandle. 

Parameters:  type  Data    structure    type:    CHANGE_FH    or 

CHANGEJLOCK 

object         Lock  or  FileHandle  (according  to  type) 

newmode    New  access  mode 
Result:  0  Change  not  allowed 

Warning:      Invalid  values  can  lead  to  a  system  crash. 
See  also:       Lock(),  Open() 
ICiose  Close  file| 

Call:  success  =  Close  (   file   ) 

DO  -36 (A6)    Dl 

BOOL  success 
BPTR  file 

Function:      Close  a  file  opened  by  the  program  itself. 

Parameters:  file  BCPL  address  of  the  file's  FileHandle. 

Result:  0  if  the  file  could  not  be  closed,  for  example,  because  a 

buffered  output  is  still  in  process. 
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See  also:       OpenQ 


DeleteFile 


Delete  a  file] 


Call:  success  =  DeleteFile  (   name   ) 

DO  -72 (A6)  Dl 

BOOL  success 
APTR  name 

Function:      Attempts  to  delete  a  file  or  directory. 

Parameters:  name  String  containing  file  or  directory  name. 

Result:  0  Could  not  be  deleted. 

See  also:       IoErrQ 


lExamineFH 


Retrieve  information  on  a  file 


Call:  success  =  ExamineFH(fh,    fib) 

DO  -390  (A6)       Dl      D2 

BOOL  success 

BPTR    fh 

STRUCT  FilelnfoBlock  *fib 

Function:      Examines  a  FileHandle  and  fills  out  a  FilelnfoBlock.  Be 
careful,  because  fib_Size  can  contain  invalid  values. 


Parameters:  fh 
fib 
Result:  0 


FileHandle 

Address  of  a  FilelnfoBlock  structure. 

Error 


IFGetC 


Read  characters  from  a  filel 


Call:  char  =  FGetC(fh) 

DO      -306 (A6)    Dl 

LONG  char 
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Function: 
Parameters. 
Result: 
|  Flush 


BPTR    fh 

Reads  a  byte  from  the  given  file  (buffered). 

fh  FileHandle 

Byte  (value  0-255)  or  -1  if  end-of-file  or  error. 


Clears  the  buffer  used  for  a  buffered  I/Q| 


Call: 


Function: 

Parameters. 
Result: 


success   =  Flush (fh) 
DO  -360 (A6)    Dl 

BOOL  success 
BPTR  fh 

Deletes  all  buffers  for  a  file.  When  reading  from  a  file,  Seek() 
is  used  to  locate  the  old  position. 

fh     FileHandle 

0      Error 


IFPutC 


Output  a  character] 


Call: 


Function: 
Parameters: 

Result: 


char  =  FPutC(fh,  char) 
DO   -312 (A6)  Dl   D2 

LONG  char 
BPTR   fh 
UBYTE  char 

Buffered  output  of  an  individual  character. 

fh  FUeHandle 

char  Output  byte 

The  printed  character  or  EOF  in  the  case  of  an  error. 
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|FRead  Read  data  blocks  from  a  file  | 

Call:  count  =  FRead(fh,   buf,    blocklen,    blocks) 

DO         -324  (A6)    Dl      D2        D3  D4 

LONG      count 

BPTR      fh 

APTR      buf 

ULONG  blocklen, blocks 

Function:      Attempts  a  buffered  read  of  the  given  number  of  blocks 
from  a  file. 

Parameters:  fh  FileHandle  to  use  for  buffered  I/O. 

buf  Buffer  for  writing  the  blocks  that  are  read. 

blocklen  Block  length 

blocks  Number  of  blocks  to  read. 

Result:  Number  of  blocks  actually  read  (EOF  or  read  error  aborts 

the  read  operation). 

Warning:      You  must  first  use  SetIoErr()  to  delete  the  error  code  if  a 
query  is  necessary. 

I  FWrite  Write  data  blocks  to  a  file  | 

Call:  count  =  FWrite  (fh,  buf,  blocklen,  blocks) 

DO     -330  (A6)  Dl   D2    D3         D4 

LONG  count 

BPTR   fh 

APTR   buf 

ULONG  blocklen, blocks 

Function:      Attempts  a  buffered  write  of  the  given  number  of  data 
blocks  to  a  file. 

Parameters:  fh  FileHandle 
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Result: 


buf  Buffer  containing  the  data  to  be  written. 

blocklen     Block  length 

blocks         Number  of  blocks  to  write. 

Number  of  blocks  actually  written  (aborted  in  the  case  of 
an  error). 


Warning:      Use  SetloErr  to  delete  the  error  code  before  using  IoErrQ. 


Ilslnteractive 


Is  a  file  a  virtual  terminal?! 


Call:  status  =  Islnteractive  (  file  ) 

DO        -216 (A6)        Dl 


BOOL  status 
BPTR  file 


Function:     Checks  a  file  to  see  if  it's  a  virtual  terminal  (for  example,  a 
console  window). 


Parameters:  file 
Result:  0 


FileHandle  of  the  file. 
Normal  file,  not  a  terminal. 


I  Lock 


Obtain  access  to  a  file  or  directory  | 


Call:  lock  =  Lock(  name,  accessMode  ) 

DO       -84 (A6)  Dl   D2 

BPTR  lock 
APTR  name 
LONG  accessMode 

Function:  Attempts  to  secure  access  to  a  file  or  directory.  This  can  be 
exclusive  access  (ACCESS_WRITE),  which  prevents  other 
programs  from  accessing  the  file,  or  shared  access 
(ACCESS_READ). 

Parameters:  name  Filename  and/or  path  name 
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Result: 


accessMode 

Access  mode 

BPTR  to  a  lock  structure  or  0. 


ILockRecord 


Obtain  access  to  part  of  a  file  | 


Call:  success  =  LockRecord(fh,  offset,  length, mode,  timeout) 

DO         -270 (A6)    Dl  D2      D3      D4    D5 

ULONG  success, off set, length, mode, timeout 
BPTR   fh 

Function:      Grants  access  to  part  of  a  file.  A  specific  timeout  period  can 
be  set. 


Parameters:  fh 

FileHandle  for  the  file. 

offset 

Start  of  record 

length 

End  of  record 

mode 

Access  mode: 

REC_EXCLUSIVE 

Exclusive  access 

REC_EXCLUSIVE_IMMED 

Exclusive  access,  ignore 

timeout 

Result: 


REC_SHARED       Shared  access 

REC_SHARED_IMMED 

Shared    access,    ignore 
timeout 

timeout       Timeout  period  in  l/50th  seconds  (0  allowed). 

0  Error  or  access  not  possible. 


ILockRecords 


Secure  access  to  several  parts  of  a  file  | 


Call:  success  =  LockRecords(record_array, timeout) 

DO  -276 (A6)  Dl  D2 
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BOOL   success 

STRUCT  RecordLock  *record_array 

ULONG  timeout 

Function:  This  function  locks  several  parts  of  the  file  at  once.  A 
specific  timeout  period  can  be  set. 

Parameters:   record_array 

List  of  RecordLock  structures. 

timeout       Timeout  period  (0  allowed) 

Result:  0  Error  or  one  or  more  of  the  records  not  free. 

I  Open  Open  a  file  | 

Call:  file  =  Open(   name,    accessMode   ) 

DO  -30 (A6)    Dl      D2 

BPTR  file 
APTR  name 
LONG  accessMode 

Function:  Attempts  to  open  an  existing  file  (MODE_OLDFILE)  or 
create  a  new  file  (MODE_NEWFILE).  If 
MODE_READWRITE  is  specified,  a  file  is  opened  and 
created,  if  it  doesn't  already  exist. 

Parameters:  name  Filename 

accessMode 

Access  mode 

Result:  BPTR  to  a  FileHandle  structure  or  0. 
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IQpenFromLock  Open  file  associated  with  a  lock| 

Call:  fh  =  OpenFromLock(lock) 

DO         -378 (A6)  Dl 

BPTR   fh.lock 

Function:      Opens  a  file  associated  with  a  given  lock.  The  access  mode 
is  determined  by  the  lock. 

Parameters:  lock  Lock  structure  of  a  file. 

Result:  FileHandle  or  0 

|  Read  Read  data  from  a  file  | 

Call:  actualLength  =  Read(    file,    buffer,    length   ) 

DO  -42 (A6)    Dl      D2  D3 

LONG  actualLength, length 
BPTR  file 
APTR  buffer 

Function:      Read  data  from  a  given  file  to  a  buffer. 

Parameters:  file  FileHandle 

buffer         Read  buffer 

length         Number  of  bytes  to  read 

Result:  Number  of  bytes  actually  read  (0  indicates  end-of-file)  or  -1 

(error). 

|  Rename  Rename  a  file  or  directory  | 

Call:  success   =  Rename  (   oldName,    newName   ) 

DO  -78 (A6)    Dl  D2 

BOOL  success 

APTR  oldName , newName 
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Function:  Assigns  a  new  name  to  a  file  or  directory.  If  a  new  path  is 
also  given,  the  renamed  object  is  moved  to  the  new 
directory. 

Parameters:  oldName     Old  name 

newName   New  name 

Result:  0  Error 


SameLock  Compare  two  locks  | 


Call:  value  =   SameLock  (lockl,    lock2) 

DO  -420 (A6)    Dl  D2 

LONG  value 

BPTR  lockl, lock2 

Function:  Compare  two  locks.  Returns  a  value  of  LOCKJSAME  if 
the  same  object  is  found,  LOCK_SAME_HANDLER  for 
different  objects  that  belong  to  the  same  handler,  or 
LOCK_DIFFERENT  if  the  handlers  are  different. 

Parameters:  lockl, lock2 

The  locks  to  be  compared. 

Result:  See  function. 

I  Seek  Change  read/write  position  in  a  file] 

Call:  oldPosition  =  Seek(    file,    position,    mode   ) 

DO  -66  (A6)    Dl      D2  D3 

LONG  oldPosition, position, mode 
BPTR  file 

Function:  Seek()  sets  the  read/write  position  within  a  file  relative  to 
the  start  of  the  file,  the  current  position,  or  the  end  of  the 
file.  The  old  position  is  returned  as  the  result. 

Parameters:  file  FileHandle  for  the  file. 
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position      Relative  value 

mode  Start,  relative,  or  end 

Result:  Old  position  relative  to  the  start  of  the  file. 

|  SetComment  Set  file  comments] 

Call:  success  =  SetComment  (   name,    comment   ) 

DO  -180 (A6)  Dl  D2 

BOOL  success 
APTR  name , comment 

Function:      Sets  new  comments  for  the  given  file. 

Parameters:   name  Filename 

comment     Comment  string  (max.  80  characters) 

Result:  DO  0  in  case  of  error 

|  SetFileDate  Set  revision  date  for  a  file| 

Call:  success  =  SetFileDate  (name,  date) 

DO         -396 (A6)     Dl     D2 

BOOL   success 

aptr   name 

STRUCT  Dates tamp  *date 

Function:      Sets  the  revision  date  for  a  file  or  directory,  as  long  as  it's 
allowed  by  the  filesystem. 

Parameters:  name  Object  name 

date  DateStamp  structure  with  new  date. 

Result:  0  Error 
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ISctFileSize" 


Set  the  size  of  a  file  I 


Call:  newsize  =  SetFileSize(fh,  offset,  mode) 

DO         -456 (A6)     Dl   D2       D3 

LONG  newsize, off set, mode 
BPTR  fh 

Function:  Sets  the  file  size  for  the  given  file,  as  long  as  this  is  allowed 
by  the  filesystem.  The  position  is  specified  the  same  as  with 
Seek(). 


Parameters:  fh 

offset 
mode 


FileHandle  for  the  file. 

Relative  value 

OFFSET_BEGINNING,  OFFSET_CURRENT 
or  OFFSET  END. 


Result: 


File  length  or  -1  (error). 


ISetProtection 


Set  protection  status  for  a  filel 


Call:  success  =  SetProtection(  name,  mask  ) 

DO        -186  Dl     D2 


Function: 


BOOL  success 
APTR  name 
LONG  mask 

Sets  the  protection  status  for  a  file  or  directory.  The  status 
consists  of  an  OR  combination  of  various  flags: 


Bit  4:  A  1 
Bit  3:  R  1 
Bit2:Wl 
Bit  1:  El 
BitO:Dl 


Parameters:  name 
mask 


file  unchanged  0 

read  not  allowed  0 

write  not  allowed  0 

not  executable  0 

delete  not  allowed  0 

Filename 

Protection  status 


file  changed 
read  allowed 
write  allowed 
executable 
delete  allowed 
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Result: 


Error 


lUnGetC 


Returns  a  byte  to  the  buffer! 


Call:  value  =  UnGetC(fh,    character) 

DO  -318 (A6)    Dl      D2 

LONG  value, character 
BPTR  fh 

Function:      Returns  a  byte  to  the  input  buffer.  If  the  value  -1  is  passed, 
the  last  character  read  from  the  buffer  is  put  back. 

Parameters:  fh  FileHandle  for  buffered  I/O. 

character    Character  or  - 1 

Result:  Returned  character  or  0  (error). 


|UnLock" 


Remove  lockl 


Call:  UnLock(    lock   ) 

-90 (A6)    Dl 

BPTR   lock 

Function:     Removes  a  lock  and  frees  the  allocated  memory. 
Parameters:  lock  BCPL  pointer  to  a  lock  structure. 


|UnLockRecord 


Free  part  of  a  filej 


Call:  success  =  UnLockRecord(fh,off set, length) 

DO        -282  (A6)      Dl  D2      D3 

BOOL  success 

BPTR   fh 

ULONG  offset, length 

Function:     Frees  part  of  a  file  that  was  locked  with  LockRecord(). 

Parameters:  fh  FileHandle  given  with  LockRecordQ. 
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Result: 


offset  Start  of  record 

length         Length  of  record 
0  Error 


UnLockRecords 


Free  several  parts  of  a  file| 


Call:  success  =  UnLockRecords (record_array) 

DO         -288 (A6)       Dl 

BOOL   success 

STRUCT  RecordLock  *record_array 

Function:      Frees  multiple  records  locked  with  LockRecords(). 

Parameters:  record_array 

List  of  records  to  free 


Result: 


0 


Error 


IVFPrintf 


Write  formatted  string  to  a  fiie| 


Call:  count  =  VFPrintf(fh,  fmt,  argv) 

DO       -354 (A6)  Dl   D2    D3 

LONG  count 

BPTR  fh 

APTR  fmt, argv [] 

Function:      Formats  a  string  and  does  a  buffered  write  of  the  result  to  a 
file. 

Parameters:  fh  FileHandle  for  the  file. 

fmt  Format  string  for  exec/RawDoFmt(). 

argv  Address  of  data  array. 

Result:  Number  of  bytes  written  or  - 1  (error). 
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[VFWritef  VFPrintf  for  BCPL  strings  | 

Call:  count  =  VFWritef(fh,    fmt,    argv) 

DO  -348 (A6)    Dl      D2        D3 

LONG  count 

BPTR    fh 

APTR  fmt, argv [] 

Functions,  Parameters,  and  Results: 

Same  as  VFPrintf,  except  the  strings  are  BSTR  or  BCPL. 

rWrite  Write  to  a  filel 

Call:  returnedLength  =  Write  (  file,  buffer,  length  ) 

DO  -48  (A6)  Dl      D2       D3 

LONG  returnedLength,  length 
BPTR  file 
APTR  buffer 

Function:     Writes  a  specified  number  of  bytes  to  a  file. 
Parameters:  file  FileHandle 

buffer         Address  of  the  bytes. 

length         Number  of  bytes  to  write. 
Result:  Number  of  bytes  actually  written. 

Open()  modes: 

MODE_OLDFILE   =  1005  ,-open  existing  file 
MODE_NEWFILE   =  1006  ; create  new  file 
MODE_READWRITE  =  1004  ;open  file  (1005  (->1006)) 

FileHandle  structure: 

Dec  Hex  STRUCTURE  FileHandle, 0 

0   $0  APTR   fh_Link        ;Exec  message 

4  $4  APTR   fh_Port        ;  answer  port  for  Packet 

8  $8  APTR   fh_Type        ;port  for  PutMsgO 
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12 

$c 

LONG 

fh_Buf 

16 

$10 

LONG 

fh_Pos 

20 

$14 

LONG 

fh_End 

24 

$18 

LABEL 

fh_Funcl 

24 

$18 

LONG 

fh_Funcs 

28 

$1C 

LONG 

fh_Func2 

32 

$20 

LONG 

fh_Func3 

36 

$24 

LABEL 

fh_Argl 

36 

$24 

LONG 

fh_Args 

40 

$28 

LONG 

fh_Arg2 

44 

$2C 

LABEL 

fh_SIZEOF 

Points  of  reference  for  Seek(): 


OFFSET_BEGINNING  =  -1  ; start  of  file 
OFFSET_CURRENT    =   0  /current  position 
OFFSET_END        =   1  ;end  of  file 
OFFSETBEGINING   =  OFFSET_BEGINNING 


Structure  ofLock(),  etc.: 


Dec  Hex  STRUCTURE  FileLock.O 


0 

$0  BPTR 

4 

$4  LONG 

8 

$8  LONG 

12 

$C  APTR 

16 

$10  BPTR 

fl_Link   ;next  Lock 
fl_Key    ; block  number  on  disk 
fl_Access  ; access  mode 
fl_Task   ; Handler  port 
fl_Volume  .-Volume  Node  (DosList) 


20  $14  LABEL    fl_SIZEOF 


SHARED_LOCK 
EXCLUSIVE_LOCK 
ACCESS_READ 
ACCESS  WRITE 


Locki)  modes: 

=  -2   ; shared  access 
=  -1  ; exclusive  access 
=  SHARED_LOCK 
=  EXCLUSIVE_LOCK 

SameLockO  values: 


LOCK_SAME        =  0  ,- objects  identical 
LOCK_SAME_HANDLER  =   1  ; objects  have  same  Handler 
LOCK_DIFFERENT    =  -1  ; completely  different  Locks 


ChangeMode()  types: 


CHANGE_LOCK  =  0  ;Lock  structure 
CHANGE_FH   =  1  ;FileHandle  structure 
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LINK_HARD  =  0 
LINK_SOFT  =  1 


REC_EXCLUSIVE 
REC_EXCLUS IVE_IMMED 

REC_SHARED 
REC_SHARED_IMMED 


MakeLink()  values: 


LockRecord()ILockRecords()  modes: 

=  0  /exclusive  access 

1  ; exclusive  with  no  waiting 

=  2  ; shared  access 

=  3  ; shared  with  no  waiting 

LockRecords()/UnLockRecords()  structure: 


Dec  Hex  STRUCTURE  RecordLock, 0 


0  $0  BPTR 

4  $4  ULONG 

8  $8  ULONG 

12  $C  ULONG 

16  $10  LABEL 


rec_FH 

rec_Offset 

rec_Length 

recMode 


;FileHandle 
; start  (offset) 
; record  length 
;Lock  type 


RecordLock_S I ZEOF 


8.  Strings 


lAddPart 


Add  filename  to  path  string  | 


Call:  success  =  AddPart  (   dirname,    filename,    size   ) 

DO  -882  (A6)    Dl  D2  D3 

BOOL     success 
APTR     dirname 

APTR     filename 
ULONG  size 

Function:  Adds  a  filename  to  a  path  name  according  to  DOS 
conventions.  The  filename  may  also  contain  path 
information.  If  the  filename  is  a  complete  path,  then  the  old 
path  is  replaced. 

Parameters:  dirname      Path  name 

filename      (path  +)filename,  7  or ':'  allowed 

size  Size  of  buffer  that  contains  dirname. 
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Result:  0  Error  (buffer  too  small) 

See  also:       Filepart(),  PathPart() 

iDateToStr  Generate  string  from  DateStampI 

Call:  success  =  DateToStr(   datetime   ) 

DO  -744 (A6)         Dl 

BOOL        success 

STRUCT  DateTime  *datetime 

Function:     Generates  a  string  for  a  DateStamp  structure  according  to 
the  given  DateTime  structure. 

Parameters:  datetime     Address  of  a  DateTime  structure,  which  must  be 

initialized  as  follows: 

dat_Stamp       Copy  of  the  DateStamp. 

dat_Format  String  format  (FORMAT_DOS 
dd-mmm-yy,  FORMATJNT  yy- 
mmm-dd,  FORMATUSA  mm- 
dd-yy  or  FORMAT_CDN  dd- 
mm-yy). 

dat_Flags  DTF_SUBST  generates  the  day 
of  the  week  (Monday,  Today...). 

dat_StrDay  Address  of  the  day  buffer  or  0  if 
not  used. 

dat_StrDate  Address  of  the  date  buffer  or  0 
if  not  used. 

dat_StrTime  Address  of  the  time  buffer  or  0  if 
not  used. 

Result:  0  DateStamp  error 

See  also:       DateStampO,  StrToDateQ 
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I  Fault 


Generate  error  message! 


Call:  success  =  Fault  (code,  header,  buffer,  len) 

DO        -468  (A6)  Dl   D2       D3       D4 

BOOL  success 
LONG  code, len 
APTR  header, buffer 

Function:  Converts  an  error  code  into  a  string  for  the  console 
window,  printer,  or  a  text  file  (with  line  feed).  This  is 
preceded  by  the  given  header  text.  Error  messages  should 
not  be  more  than  80  characters,  and  headers  should  not  be 
more  than  60.  If  a  certain  code  has  no  message  text,  the 
string  "Error  code  <number>"  is  used. 

Parameters:  code  Error  code  from  IoErr(). 

header  Header  text 

buffer  Buffer  for  the  complete  error  message. 

len  Buffer  length 

Result:  0  Buffer  too  small  or  some  other  error. 


IFGets 


Read  a  line  from  a  file  | 


Call:  buffer  =  FGets(fh,   buf,    len) 

DO  -33  6 (A6)    Dl      D2         D3 

APTR  buffer, buf 
BPTR  fh 
ULONG  len 

Function:  Reads  a  line  from  a  file  into  a  buffer.  One  character  less 
than  the  length  of  the  buffer  can  be  read,  because  the  last 
character  in  the  buffer  must  always  be  set  to  0.  If  the  entire 
line  fits  in  the  buffer,  the  character  before  the  null  byte  is  an 
end-of-line  code  (LF  or  CR).  The  I/O  is  buffered. 


Parameters:  fh 


FileHandle 
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buf 

len 


Buffer  address 
Buffer  length 


Result: 


IFilePart 


Address  of  the  buffer  or  0  if  no  characters  could  be  read.  If 
the  end  of  the  file  is  reached  before  the  call,  IoErr()=0.  If  an 
error  occurs,  IoErr()oO. 


Extract  the  filename  from  a  path  specification 


Call:  fileptr  =  FilePart(  path  ) 

DO        -870 (A6)   Dl 

APTR  fileptr, path 

Function:      Returns  the  start  address  for  the  file  in  a  given  path 
specification. 

Parameters:  path  Path  string  according  to  DOS  conventions. 

Result:  Start  address  for  the  file. 

See  also:       PathNameQ 


|FindArg~ 


Find  a  keyword  in  an  argument  string  | 


Call:  index  =  FindArg( template,    keyword) 

DO  -804 (A6)    Dl  D2 

LONG  index 

APTR  keyword, template 

Function:      Returns  the  argument  number  for  a  given  keyword. 

Parameters:  keyword     Keyword  to  search  for. 

template      Argument  string 

Result:  Argument  number  of  the  given  keyword  or  -1  if  the 

keyword  was  not  found. 
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IFPuts 


Write  a  string  to  a  file| 


Call:  error  =  FPuts(fh,    str) 

DO         -342 (A6)    Dl      D2 

LONG  error 
BPTR  fh 
APTR  str 

Function:      Buffered  write  of  a  string  to  a  file. 

Parameters:  fh  FileHandle 

str  String  ending  in  0. 

Result:  Negative     Error 


IGetArgStr 


Retrieves  an  argument  string  from  CLl| 


Call: 


ptr  =  GetArgStrO 
DO    -534(A6) 

APTR  ptr 


Function:  Returns  the  argument  address  found  in  the  A0  register 
when  the  program  is  started.  This  is  only  useful  for  high 
level  languages  that  do  not  use  an  argument  parser. 

Result:  Address  of  the  argument  string  from  CLI  or  0. 


|  GetCurrentDirName        Retrieve  the  name  of  the  current  directory 


Call:  success   =  GetCurrentDirName  (buf,    len) 

DO  -564 (A6)  Dl        D2 

BOOL  success 
APTR   buf 
LONG  len 

Function:      Gets  the  name  of  the  current  directory  from  the  CLI 
structure  of  its  own  process. 
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Parameters:  buf  Buffer  for  the  name. 

len  Buffer  length 

Result:  0  No  CLI  structure  or  no  directory. 

|  GetProgramName  Returns  the  program's  own  name  | 

Call:  success   =  GetProgramName  (buf ,    len) 

DO  -576 (A6)  Dl        D2 

BOOL  success 
APTR  buf 
LONG    len 

Function:      Copies  the  program  name  from  the  CLI  structure  to  a 
buffer. 

Parameters:  buf  Buffer  address 

len  Buffer  length 

Result:  0       Buffer  too  small  or  CLI  structure  not  found. 


GetPrompt Retrieve  the  prompt  string  for  a  process | 


Call:  success   =  GetPrompt  (buf ,    len) 

DO  -588  (A6)       Dl        D2 

BOOL  success 
APTR   buf 
LONG  len 

Function:      Copies  the  prompt  string  from  the  CLI  structure  to  a  buffer. 

Parameters:  buf  Buffer  address 

len  Buffer  length 

Result :  0  Buffer  too  small  or  CLI  structure  not  found. 
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IMatchPattern 


Test  a  string  against  a  pattern  | 


Call:  match  =  MatchPattern  (pat ,  str) 

DO       -846 (A6)      Dl    D2 

BOOL  match 
APTR  pat, str 

Function:      Checks  to  see  if  the  given  string  matches  a  given  pattern. 

Parameters:  pat  Pattern  string  from  ParsePattern(). 

str  String  to  be  checked. 

Result:  0  String  does  not  match  pattern. 


INameFromFH" 


Get  the  filename  from  the  FileHandlel 


Call:  success  =  NameFromFH(fh,    buffer,    len) 

DO  -408  (A6)         Dl      D2  D3 

BOOL  success 
BPTR   fh 
APTR  buffer 
LONG  len 

Function:     Writes  the  file  and  path  name  of  the  given  FileHandle  to  a 
buffer. 


Parameters:  fh 

buffer 
len 
Result:  0 

INameFromLock 


FileHandle 

Buffer  for  result  string. 

Buffer  length 

Error  or  buffer  too  small. 


Retrieve  the  name  and  path  of  a  lock  | 


Call:  success  =  NameFromLockdock,   buffer,    len) 

DO  -402 (A6)  Dl  D2  D3 
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BOOL  success 
BPTR  lock 
APTR  buffer 
LONG  len 

Function:      Writes  the  name  and  path  of  the  given  lock  to  a  buffer. 
Parameters:  lock  Lock 

buffer         Buffer 

len  Buffer  length 

Result:  0  Error  (IoErr()=ERROR_LINE_TOO_LONG) 


IParsePattern 

Call: 


Generate  token  string  for  MatchPatternQ] 


Iswild  =  ParsePattern (Source, Dest,DestLength) 
dO        -840 (A6)      Dl      D2    D3 

LONG  IsWild,DestLength 
APTR  Source, Dest 

Function:     Creates  a  token  string  for  the  MatchPattern()  function. 

Parameters:  source         Pattern  string 

dest  Buffer  for  token  string. 

DestLength 

Buffer  length  (min.  2*Source+2). 

Result:  1  string  contains  wildcards  (#,  ?  etc.) 

0  string  contains  no  wildcards. 
-1  buffer  too  small  or  error. 


[PathPart 


Call:  fileptr  =  PathPart  (  path  ) 

DO         -876 (A6)   Dl 

APTR  fileptr, path 


Retrieve  the  end  of  a  path  specification  | 
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Function:      Returns  the  address  of  the  end  of  a  path  specification. 

Parameters:  path  Filename   (with   path)   according   to   DOS 

standards. 

Result:  Address  of  the  part  of  the  path  that  disappears  when 

another  file  is  selected  in  a  file  selection  box. 

See  also:       FilePart() 

|  SplitName  Retrieve  part  of  a  path  specification  | 

Cfl//.'         newpos  =  SplitName  (name,  separator,  buf,  oldpos,  size) 
DO        -414 (A6)   Dl     D2  D3    D4       D5 

WORD  newpos, oldpos 
APTR  name, buf 
UBYTE  separator 
LONG   size 

Function:      Copies  the  next  part  of  a  complete  file/path  name  to  a 
separate  buffer. 

Parameters:  name  Filename  with  path. 

separator  ASCII  code  of  the  separation  character. 

buf  Buffer 

oldpos  Old  position  in  string. 

size  Buffer  size  in  bytes. 

Result:  New  start  position  for  the  next  call  (newpos->oldpos)  or  - 1 . 

|  StrToDate  Convert  a  string  to  a  DateStamp  [ 

Call:  success  =  StrToDate  (  datetime  ) 

.  DO         -750 (A6)    Dl 

BOOL   success 

STRUCT  DateTime  *datetime 
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Function:      Fills  in  a  DateStamp  structure  using  the  information  from  a 
string. 

Parameters:  datetime      Initialized  (!)  DateTime  structure. 

Result:  0  Error 

See  also:       DateToStr(),  ubraries/datetime.h 

IStrToLong  Convert  a  decimal  string  to  a  longwordl 

Call:  characters  =  StrToLong(  string,  value) 

DO  -816 (A6)      Dl  D2 

LONG  characters 
APTR  string, value 

Function:      Converts  a  string  containing  a  decimal  value  into  a 
longword. 

Parameters:  string  Decimal  string 

value  Address  of  the  resulting  longword. 

Result:  Number  of  decimal  places  found  or  -1  (longword  is  then  set 

toO). 

StrToDate()/DateToStr()  structure: 

Dec  Hex  STRUCTURE   DateTime , 0 

0   $0  STRUCT  dat_Stamp,ds_SIZEOF  ; DateStamp  structure 

12  $C  UBYTE   dat_Format  ; dat_StrDate  format 

13  $D  UBYTE   dat_Flags  ; Flags  (see  below) 

14  $E  CPTR    dat_StrDay  ;day  of  the  week  string 
18  $12  CPTR    dat_StrDate  ,-date  string 

22  $16  CPTR    dat_StrTime         ;time  string 
26  $1A  LABEL    dat_SIZEOF 

LEN_DATSTRING  =  16  ; length  of  a  date  string 

Flags,  Bits: 

DTB_SUBST  =  0,  DTF_SUBST  =  1  ;create  "Today" , "Tomorrow" .. . 
DTB_FUTURE=  1,  DTF_FUTURE=  2  ;a  future  day 
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Date  formats: 

FORMAT_DOS  =  0  ;dd-mmm-yy  DOS  format 
FORMAT_INT  =  1  ;yy-mm-dd   international  format 
FORMAT_USA  =  2  ;mm-dd-yy  USA  format 
FORMAT_CDN  =  3  ;dd-mm-yy  Canadian  format 
FORMAT_MAX  =  FORMAT_CDN 


9.  Time 

[CompareDates  Compare  two  UateStamps  I 

Call:  result  =  CompareDates  (datel,date2) 

DO  -73  8 (A6)  Dl  D2 

LONG       result 

STRUCT  DateStamp  *datel 

STRUCT  DateStamp  *date2 

Function:      Compares  the  dates  given  in  two  DateStamp  structures. 

Parameters:  datel/date2 

DateStamp  structures 

Result:  negative:     datel  later  than  date2 

0:  datel  equals  date2 

positive:      date2  later  than  datel 

See  also:       DateStampO 

[DateStamp  Retrieves  the  current  time| 

Call:  DateStamp  (  ds   ) 

-192 (A6)         Dl 

STRUCT  DateStamp  *ds 

Function:     Fills  the  given  DateStamp  structure  with  the  current  time. 

Parameters:  ds  Address  of  a  DateStamp  structure. 
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Result:  The  structure  is  filled. 


|  Delay  Suspend  own  process  for  a  certain  time  period  | 

Call:  Delay  (   ticks   ) 

-198 (A6)    Dl 

ULONG   ticks 

Function:      Own  process  is  suspended  for  the  given  time  period. 

Parameters:  ticks  Time  period  in  l/50th  second. 

IWaitForChar  Wait  for  inputj 

Call:  status   =  WaitForChar(    file,    timeout    ) 

DO  -204  (A6)  Dl  D2 

BOOL  status 
BPTR   file 
LONG  timeout 

Function:  Waits  a  specified  number  of  microseconds  (1/1000000)  to 
see  if  a  character  can  be  successfully  read  from  the  given 
file.  This  is  very  important  for  working  with  ports  and 
terminals. 

Parameters:  file  FileHandle  for  the  file. 

timeout       Time  period  in  microseconds. 

Result:  0  No  character  received  during  the  wait  period. 


Dec  Hex  STRUCTURE  DateStamp.O 

0   $0  LONG   ds_Days    ;days  since  Jan.  1,  1978 
4   $4  LONG  ds_Minute  ;minutes  since  midnight 
8   $8  LONG  ds_Tick    ; ticks  since  last  minute 
12   $C  LABEL  ds_SIZEOF 

TICKS_PER_SECOND  =  50    ; number  of  ticks  per  second 
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10.  Environment  Variables 


I  Delete  Var 


Delete  local  environment  variable  | 


Call: 


success  =  DeleteVar(  name,  flags  ) 
DO        -912 (A6)    Dl    D2 

BOOL  success 
APTR  name 
ULONG  flags 


Function:      Delete  a  local  ENV  variable. 


Parameters:  name 


flags 


Result: 


String  address  with  variable  name  (structured 
like  a  filename). 

Flags  for  variable  type  and  function. 

GVF_LOCAL_ONLY 

Local  variable  (default) 

GVF_GLOBAL_ONLY 

Global  variable 

Error. 


See  also:       GetVarO,  SetVar() 


|  Find  Var 


Find  local  variable] 


Call:  var  =  FindVar(  name,  type  ) 

DO     -918 (A6)  Dl     D2 

STRUCT  LocalVar  *var 
APTR   name 
ULONG  type 

Function:      Retrieves  a  local  variable. 

Parameters:  name  Variable  name  (structured  like  a  path  name) 

type  Variable  type 
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Result:  LocalVar  structure  or  0 

See  also:       GetVarQ,  SetVar(),  DeleteVar(),  dos/var.h 


IGetVar 


Retrieve  the  value  of  a  variable! 


Call:  len  =  GetVar(  name,  buffer,  size,  flags  ) 

DO     -906 (A6)  Dl    D2      D3     D4 

LONG  len, size 
APTR  name , bu  f  f  er 
ULONG  flags 

Function:  Returns  the  value  of  an  environment  variable.  If 
GVF_BINARY_VAR  is  not  set,  the  function  is  interrupted 
when  an  LF  character  is  encountered. 


Parameters:  name 
buffer 
size 
flags 


Result: 


Variable  name  (AmigaDOS  path) 

Buffer  for  the  variable  contents. 

Buffer  size 

Variable  type 

GVF_GLOBAL_ONLY 

Global  ENV  variable 

GVFLOCAL.ONLY 

Process-specific     ENV 
variable 

GVF_BINARY_VAR 

With  control  character 


Total  length  of  the  variable  (may  be  different  from  the 
buffer  contents  if  the  buffer  terminates  with  0)  or  -1  in  the 
case  of  an  error  (variable  not  found). 


See  also:       SetVar(),  DeleteVarQ,  dos/var.h 
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ISetVar 


Create  or  set  the  value  of  a  variable  | 


Call:  success  =  SetVar(  name,  buffer,  size,  flags  ) 

DO        -900  (A6)  Dl    D2       D3     D4 

BOOL  success 
APTR  name , bu  f  f  er 
LONG  size 
ULONG  flags 

Function:      Sets  a  local  or  environment  variable.  ASCII  strings  are  only 
recommended. 


Parameters. 

name 

Filename  of  the  variable. 

buffer 

Contents  of  variable. 

size 

Variable  size  (-1  =  string  ending  in  0) 

flags 

Variable  type 

Result: 

0 

Eiror 

See  also: 

GetVarO 

,  Delete  VarQ,  dos/var.h 

Structure  of  prLocalVars  list: 


Dec  Hex  STRUCTURE  LocalVar, 0 

0   $0  STRUCT   lv_Node,LN_SIZE  ;node 

14   $E  UWORD   lv_Flags  ;type 

16  $10  APTR    lv_Value  ;buffer 

20  $14  ULONG   lv_Len  ,-buffer  length 
24  $18  LABEL   LocalVar_SIZEOF 

LNJYPE  bits  in  Ivjfode: 

LV_VAR      =0       ;a  variable 
LV_ALIAS    =1       ;an  ALIAS  definition 
LVB_IGNORE  =   7,  LVF_IGNORE      =   $80 
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Values  for  variable  functions: 

GVB_GLOBAL_ONLY  =  8,  GVF_GLOBAL_ONLY  =  $100 
GVB_LOCAL_ONLY  =  9,  GVF_LOCAL_ONLY  =  $200 
GVB_BINARY_VAR   =  10,  GVF_BINARY_VAR   =  $400 

//.  Errors  and  Requesters 

|  Err  or  Report  Display  Retry/Cancel  error  requester  | 

Call:  status  =  ErrorReport(code,  type,  argl,  device) 

DO       -480  (A6)     Dl    D2    D3    A0 

BOOL   status 

LONG   code, type 

ULONG   argl 

STRUCT  MsgPort  *device 

Function:      Displays  the  appropriate  error  requester. 
Parameters:  code  Error  code  (ERROR_...,  ABORT....) 

type  Requester  type: 

REPORTLOCK     argl  is  a  lock  (BPTR). 

REPORTJH  argl     is    a    FileHandle 

(BPTR). 

REPORT.VOLUME 

argl   is  a  volume  node 
(CPTR). 

argl  Parameter  (according  to  type) 

device        (optional)  HandlerPort  address  (only  needed 
for  REPORT_LOCK  with  argl  =0) 

Result:  DOS_TRUE  'Cancel' or  error 

0  'Retry'  or  DISKINSERTED  (for  certain  errors) 
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IoErr 


Retrieve  additional  system  error  information] 


Call: 


Function: 


Result: 
See  also: 


error  =  IoErr ( ) 
DO      -132 (A6) 

LONG  error 

For  functions  that  return  a  value  of  0  when  errors  occur. 
IoErr()  is  used  to  retrieve  more  information  on  the  cause  of 
the  error.  Other  functions  use  IoErr()  to  return  a  second 
result  to  accommodate  programming  in  C. 

Error  code  or  second  result. 

OpenQ,  DoPktQ 


IPrintFault 


Send  error  message  to  the  output  channel] 


Call:  success   =   PrintFault  (code,    header) 

DO  -474 (A6)         Dl  D2 

BOOL   success 
LONG   code 
APTR  header 

Function:  The  given  header  string  is  combined  with  the  error  message 
associated  with  the  given  error  code  and  sent  in  a  buffered 
output  to  the  default  output  channel. 

Parameters:  code  Error  code  (see  IoErr()) 

header        Header  text  to  precede  the  error  message  text. 

Result:  0  Error 


IPutStr 


Send  a  string  to  the  default  output  channel] 


Call: 


error 

■  =  PutStr( 

3tr) 

DO 

-948(A6) 

Dl 

LONG 

error 

APTR 

str 
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Function:      Buffered  output  of  a  given  string  to  the  default  output 
channel. 


Parameters:  str  Output  string 

Result:  0  in  the  case  of  an  error. 


ISetloErr 


Set  error  codel 


Call:  oldcode  =  SetloErr  (code) 

DO  -462 (A6)    Dl 

LONG  code 

Function:      Sets  a  new  value  for  the  result  of  the  IoErr()  function 
(pr_Result2). 


Parameters:  code 


Error  code  for  IoErrQ. 


Result:  oldcode      Previous  value  of  pr_Result2. 

IoErr()  error  codes: 


ERROR_NO_FREE_STORE  =  103 

ERROR_TASK_TABLE_FULL  =  105 

ERROR_BAD_TEMPLATE  =  114 

ERROR_BAD_NUMBER  =  115 
ERROR_REQUIRED_ARG_MISSING     =  116 

ERROR_KEY_NEEDS_ARG  =  117 

ERROR_TOO_MANY_ARGS  =  118 

ERROR_UNMATCHED_QUOTES  =  119 

ERROR_LINE_TOO_LONG  =  120 

ERROR_FILE_NOT_OBJECT  =  121 
ERROR_INVALID_RESIDENT_LIBRARY=  122 

ERROR_NO_DEFAULT_DIR  =201 

ERROR_OBJECT_IN_USE  =  202 

ERROR_OBJECT_EXISTS  =20  3 

ERROR_DIR_NOT_FOUND  =  204 

ERROR_OBJECT_NOT_FOUND  =205 

ERROR_BAD_STREAM_NAME  =20  6 

ERROR_OBJECT_TOO_LARGE  =  207 

ERROR_ACTION_NOT_KNOWN  =209 
ERROR_INVALID_COMPONENT_NAME   =210 

ERROR_INVALID_LOCK  =211 

ERROR_OBJECT_WRONG_TYPE  =212 


not  enough  storage  space 

too  many  Tasks 

command  format  error 

invalid  value 

missing  a  required  argument 

keyword  with  no  argument 

too  many  arguments 

quotes  missing 

line  too  long 

not  a  normal  file 

error  in  header  Hunk 

no  default  directory 

object  being  used 

object  already  exists 

unknown  directory 

object  could  not  be  found 

invalid  name 

object  is  too  big 

unknown  Packet 

invalid  component  name 

invalid  Lock  structure 

wrong  object  type 
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ERROR_DISK_NOT_VALIDATED  =213 

ERROR_DISK_WRITE_PROTECTED  =  214 
ERROR_RENAME_ACROSS_DEVICES    =  215 

ERROR_DIRECTORY_NOT_EMPTY  =216 

ERROR_TOO_MANY_LEVELS  =217 

ERROR_DEVICE_NOT_MOUNTED  =  218 

ERROR_SEEK_ERROR  =219 

ERROR_COMMENT_TOO_BIG  =220 

ERROR_DISK_FULL  =221 

ERROR_DELETE_PROTECTED  =222 

ERROR_WRITE_PROTECTED  =223 

ERROR_READ_PROTECTED  =  224 

ERROR_NOT_A_DOS_DISK  =  225 

ERROR_NO_DISK  =  226 

ERROR_NO_MORE_ENTRIES  =  2  32 

ERROR_IS_SOFT_LINK  =23  3 

ERROR_OBJECT_LINKED  =234 

ERROR_BAD_HUNK  =235 

ERROR_NOT_IMPLEMENTED  =23  6 

ERROR_RECORD_NOT_LOCKED  =  240 

ERROR_LOCK_COLLISION  =  241 

ERROR_LOCK_TIMEOUT  =  242 

ERROR_UNLOCK_ERROR  =  243 

ERROR_BUFFER_OVERFLOW  =  3  03 

ERROR_BREAK  =  3  04 

ERROR_NOT_EXECUTABLE  =3  05 


disk  is  not  validated 

disk  is  write-protected 

rename  error 

directory  is  not  empty 

too  many  levels 

unknown  device 

Seek()  error 

comment  too  long 

disk  is  full 

delete  protected 

write  protected 

read  protected 

not  a  DOS  disk 

no  disk  found 

end  was  reached 

software  link 

object  linked 

invalid  Hunk  type 

not  implemented 

(see  LockRecord( ) ) 

Lock  collision 

Lock  timeout  period  expired 

Unlock  error 

buffer  too  small 

break  character 

not  executable 


FAULT_MAX   =  82  ;max.  length  of  an  error  string 

Error  message  structure: 

Dec  Hex  STRUCTURE  ErrorString, 0 
0   $0  APTR    estr_Nums 
4   $4  APTR   estr_Strings 
8   $8  LABEL   ErrorString_SIZEOF 


ErrorReport()  types: 


REPORT_STREAM  =  0 
REPORT_TASK  =  1 
REP0RT_L0CK  =  2 
REP0RT_V0LUME  =  3 
REPORT_INSERT  =  4 


"please  insert  volume. 
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ErrorReport()  error  codes: 

ABORT_DISK_ERROR  =296  ; read/write  error 
ABORT_BUSY       =  288  ; "You  MUST  replace...* 

DOS  boolean  values: 


DOSTRUE 
DOSFALSE 


-1  ;true 
0  ; false 


General  values: 


BITSPERBYTE 

BYTESPERLONG 

BITSPERLONG 

MAXINT 

MININT 


8  ;  8  bits  =  1  byte 
=         4  ;4  bytes  =  1  long 
=        32  ;32  bits  =  1  long 
=  $7FFFFFFF  ; maximum  LONG  value 
=  $80000000  .-minimum  LONG  value 

Basis  structure: 


Dec 

Hex 

STRUCTURE  DosLibrary,0 

0 

$0 

STRUCT 

dl_lib,LIB_SIZE 

Library  node 

34 

$22 

APTR 

dl_Root 

RootNode 

38 

$26 

APTR 

dl_GV 

BCPL 

global  vector 

42 

$2A  LONG 

dl_A2 

PRIVATE 

46 

$2E  LONG 

dl_A5 

PRIVATE 

50 

$32 

LONG 

dl_A6 

PRIVATE 

54 

$36 

APTR 

dl_Errors 

array  with  error  messages 

58 

$3A  APTR 

dl_TimeReq 

PRIVATE:  timer  request 

62 

$3E 

APTR 

dl_UtilityBase 

PRIVATE:  utility  library 

66 

$42 

LABEL 

dl_SIZEOF 

Dec 

Hex 

STRUCTURE  RootNode.O 

0 

$0 

BPTR 

rn_TaskArray 

;  CLI  Process  Array  [ 0 ] =number 

4 

$4 

BPTR 

rn_ConsoleSegmenl 

;CLI  SegList 

8 

$8 

STRUCT 

rn_Time,  ds_SIZE01 

? 

; current  time 

20 

$14 

LONG 

rn_RestartSeg 

;D\disk  validator  SegList 

24 

$18 

BPTR 

rn_Info 

; Info  structure 

28 

$1C 

BPTR 

rn_FileHandlerSe< 

jment 

;FileHandler 

32 

$20 

STRUCT 

rn_CliList,MLH_S 

tZE 

;CLI  processes 

44 

$2C 

APTR 

rn_BootProc 

; PRIVATE:  pr_MsgPort 

48 

$30 

BPTR 

rn_She 1 lSegment 

;Shell  SegList 

52 

$34 

LONG 

rn_Flags 

; Flags 

56 

$38 

LABEL 

rn_SIZEOF 

RNB_WILDSTAR  =  24,  RNF_WILDSTAR  =  $1000000 
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Dec  Hex  STRUCTURE  CliProcList, 0 

0   $0  STRUCT  cpl_Node,MLN_SIZE  ;for  linking 

8  $8  LONG    cpl_First         ; first  CLI  number 

12   $C  APTR    cpl_Array         ;CLI  Process  Array 

16  $10  LABEL    cpl_SIZEOF 


Dec 

Hex  STRUCT!. 

IRE  Doslnfo,  0 

0 

$0  BPTR 

di_McName 

; network  name  of 

device 

4 

$4  BPTR 

di_DevInfo 

;list  of  logical 

devices 

8 

$8  BPTR 

di_Devices 

; devices 

12 

$C  BPTR 

di_Handlers 

/Handlers 

16 

$10  APTR 

di_NetHand 

; current  network 

Handler 

20 

$14  STRUCT 

di_DevLock, SS_SIZE 

; PRIVATE ! ! ! 

66 

$42  STRUCT 

di_EntryLock, 

ss. 

.SIZE 

; PRIVATE ! ! ! 

112 

$70  STRUCT 

di_DeleteLock, 

ss. 

.SIZE 

; PRIVATE ! ! ! 

158 

$9E  LABEL 

di_SIZEOF 

Example 

The  volume  of  these  new  functions  is  overwhelming.  It's  difficult  to 
update  existing  programs  by  replacing  the  old  functions  with  new  ones. 
Assembler  programmers  should  prepare  for  some  big  changes  to  their 
programs,  because  the  query  of  arguments  has  been  simplified  and 
automated.  This  is  a  completely  different  approach  to  programming.  As  a 
result,  programming  that  conforms  to  the  operating  system  is  easier  to 
achieve  in  Assembler  than  in  higher  level  languages. 

Since  the  main  routines  of  all  CLI  commands  are  now  located  in  the 
operating  system,  extremely  short  programs  are  possible.  As  an 
introduction  to  OS  2  programming,  it  is  recommended  to  try  a  few  CLI 
commands  first,  and  then  gradually  work  up  to  larger  programs.  A 
disadvantage  with  Assembler  used  to  be  the  complicated  argument 
queries;  this  has  been  eliminated  with  OS  2.  We  will  use  a  simple  CLI 
command  to  help  you  through  the  programming  procedure.  For  this 
exercise  we  want  to  emphasize  the  basic  structure  and  argument  queries, 
so  we  will  construct  a  command  that  is  executed  using  a  new  DOS 
function:  AddBuffers. 

We  are  not  referring  to  the  long,  slow  CLI  command  (written  in  C)  of  the 
same  name.  Instead,  we  are  creating  a  completely  new  command  that  has 
the  same  function.  We  will  also  have  to  mention  some  of  the  dangers  of 
using  your  own  custom  routines. 
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The  AddBuffers  functions  receives  a  device  name  and  a  delta  value, 
which  may  also  be  negative.  This  number  represents  the  number  of 
buffers  to  be  added.  The  function  result  will  be  the  current  number  of 
available  buffers.  This  command  will  be  able  to  simply  query  the  number 
of  available  buffers  or  change  it  by  passing  a  delta  value.  The  first 
parameter  is  the  device  name,  and  this  parameter  is  required  with  the 
function  call.  If  a  second  parameter  is  given,  it  must  be  a  number.  This 
number  will  be  taken  as  the  delta  value.  We  will  call  our  new  command 
'Buffer'.  The  following  is  the  program  header: 

************************ *<par t -1>* *********************** * 

**_______________________________________.________________** 

**      CLI  command  structure  under  OS  2  (v37)  ** 

**      example  of  a  new  AddBuffers  command  ** 

** ** 

**       Call:  Buffer  DRIVE/A, BUFFERS/N  ** 

**      DRIVE    -  drive  letter  ** 

**      BUFFERS  -  optional,  number  of  buffers  to  add  (+)** 

**  or  subtract  (-)  ** 

** ** 


**      written  (w)  1991  by  Stefan  Maelger  ** 

** _______ ______________ _________ ________________________** 

INCLUDE_VERS_ON  =    3  6 

RETURN_OKAY  =     0 

RETURN_FAIL  =    20 

ERROR_INVALID_RESIDENT_LIBRARY  =   122 

ThisTask  =27  6 

pr_Result2  =   148 

_LVOOpenLibrary  =  -552 

_LVOCloseLibrary  =  -414 

_LVOIoErr  =  -132 

_LVOPrintFault  =  -474 

_LVOAddBuffers  =  -732 

_LVOReadArgs  =  -798 

_LVOFreeArgs  =  -858 

_LVOVPrintf  =  -954 

**************** *******<part-2>* ******************  ******** 
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Here  we  have  defined  the  purpose  of  the  program.  All  of  the  required 
system  values  have  been  set  and  the  Include  files  have  been  linked.  Our 
program  should  be  re-entrable,  meaning  it  can  be  kept  in  memory  via 
RESIDENT  after  setting  the  PURE  flag.  In  order  to  do  this,  we  must  save 
all  registers  from  number  2  on  up  before  we  use  them.  The  longword  at 
address  4  contains  the  address  of  the  operating  system  base  structure. 
This  can  vary,  depending  on  the  operating  system  and  the  available 
memory.  This  same  address  is  also  the  base  address  of  the  main  library 
EXEC,  which  can  then  be  used  to  get  the  base  address  of  the  DOS 
library. 

***********************<par£_2>***** ************** ******** 
SECTION  Program, CODE 

_Start 

movem.l  d2-d6/a6, -(a7)       ;save  registers 

** 

**  Open  the  DOS-Library 

** 

movea.l  $4.w,a6  ; load  ExecBase 

lea  _DOSName(pc) , al  ; Library  name 

moveq  #INCLUDE_VERSION,dO  ;OS  2,  v36  and  up 

jsr  _LVOOpenLibrary(a6)  ; OpenLibrary (al,dO) 

moveq  #RETURN_FAlL,d4  ; error  for  DOS 

move . 1  dO , d5  ; save  DosBase 

beq.s  _NotDOS  ;=>  if  DosBase=0 


*********************** 


<  Par t - 3  >**************************  * 

All  of  the  functions  required  for  this  command  are  available,  starting  with 
version  36  (first  version  of  OS  2).  This  version  number  must  be  specified. 
The  D4  register  saves  the  value  returned  from  CLI,  which  we  immediately 
set  to  an  error.  This  is  only  changed  to  'no  error'  after  successful 
initialization.  This  saves  us  a  lot  of  writing.  If  DOS  could  not  be  opened, 
which  should  only  occur  with  older  OS  versions,  then  we  branch  to  the 
appropriate  error  handling  routine. 

Some  of  you  will  have  noticed  that  we  made  no  efforts  to  save  the  value 
returned  from  CLI  (A0=ArgBuf,  D0=ArgLen).  With  OS  2,  this  is  no 
longer  necessary.  We  can  get  the  arguments  with  the  DOS  function 
ReadArgs,  which  handles  all  the  work  of  passing  arguments  from  the 

user. 
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******************* ****<part-3>** ****************  ********* 
** 


**  Get  CLI  arguments 

** 

exg 

d5,a6 

;  Store 

argument  field  in 

clr.l 

-<a7) 

clr.l 

-(a7) 

clr.l 

-(a7) 

clr.l 

-(a7) 

;  Query 

arguments 

lea 

_Template (pc) , aO 

move . 1 

aO,dl 

move . 1 

a7,d2 

moveq 

#0,d3 

jsr 

_LV0ReadArgs(a6) 

move . 1 

d0,d6 

bne.s 

_parseArgs 

;Exec<->Dos 


;Dummy  (size  divisible  by  16!) 
;Dummy  (size  divisible  by  16!) 
;Arg[2] 
;Arg[l] 


; argument  description 
;to  dl  for  call 
.•argument  field  to  d2 
;no  RDArgs  structure 
; ReadArgs (dl, d2 , d3 ) 
;save  RDArgs  structure 
;if  RDArgsoO  (okay) 


*********************** 


<Part-4>*************************** 


ReadArgs  expects  a  string  ending  with  a  null  byte.  This  string  describes 
all  of  the  arguments  involved.  In  it,  each  argument  name  is  given 
followed  by  the  argument  type.  The  description  of  each  argument  is 
separated  by  a  comma.  In  our  case,  this  string  will  contain 
'DRIVE/A,BUFFERS/N'.  Since  we  have  described  two  arguments  in  the 
string,  we  need  at  least  two  longwords  in  the  argument  field  to  pass 
them.  In  order  to  avoid  a  system  crash,  you  should  always  make  the  field 
size  in  bytes  divisible  by  16.  There's  no  need  to  get  extra  memory 
because  there  is  sufficient  space  in  the  stack  for  four  longwords.  A  value 
of  0  is  passed  as  the  last  parameter.  An  RDArgs  structure  obtained  with 
ReadArgs  would  be  passed  to  this  location,  but  is  not  necessary  in  our 
case. 

WARNING:  The  argument  field  must  be  filled  with  null  bytes  before  the 
call. 

The  returned  RDArgs  structure  is  saved  because  this  must  be  freed  later. 
We  test  the  result  for  errors  or  for  user  interrupt.  If  everything  is  okay,  we 
continue  to  evaluate  the  arguments;  otherwise  an  error  handling  routine 
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is  needed.  Normally,  CLI  commands  report  the  cause  of  an  error  using  a 
readable  message.  This  is  handled  by  the  PrintFault  function,  which  uses 
the  result  of  IoErr  as  a  parameter. 

********* **************<part_4> *********** **************** 
; ;  ReadArgs  error:  set  return  address 

pea     _FreeStack(pc)       ,-for  following  routine 

** 

**  Subroutine 

**  Get  DOS  error  and  output  cause  as  message  text 

** 

_Zerror 

jsr  _LV0IoErr(a6)  ,- IoErr  ( ) 

move.l  dO,dl  ; error  code  to  dl 

moveq  #0,d2  ;no  header  text 

jmp  _LV0PrintFault(a6)  ; ->PrintFault (dl, d2) 

************ ******** ***<part-5>*** ***************** ******* 

In  the  'Zerror'  routine,  we  assume  that  the  DosBase  is  stored  in  A6  and 
the  D2  register  can  be  changed  at  any  time.  Therefore,  we  don't  need  to 
save  any  of  the  registers  and  can  jump  to  the  PrintFault  routine  with  a 
JMP  command.  This  corresponds  to  a  JSR  followed  by  an  RTS.  This  part 
of  the  program  is  structured  as  a  subroutine  so  that  it  doesn't  have  to  be 
repeated  for  every  error.  In  the  case  of  a  ReadArgs  error,  we  jump 
directly  into  this  routine.  Therefore,  we  must  first  store  a  return  address 
on  the  stack  with  PEA. 

Now  we  come  to  the  part  of  the  program  where  the  arguments  are 
evaluated. 

WARNING:  Freeing  RDArgs  is  forbidden  at  this  point,  since  this  could 
cause  the  entries  of  the  argument  field  to  point  to  undefined  memory 
blocks.  As  long  as  we  are  working  with  the  argument  field,  RDArgs  must 
not  be  manipulated. 

***********************<P££.£_5;>  *********************  ****** 

** 

**  Evaluate  arguments 

** 

_parseArgs 
moveq   #RETURN_OK,d4        ;save  return  code 
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test  if  two  arguments  were  given 


move . 1 

4(a7),d0 

get  Arg[2]  (buffer) 

beq.s 

_AvailBuf fer 

;if  Arg[2]=0 

;  execut 

e  'Buffers  xxx  yyy' 

command 

movea . 1 

dO,aO 

Arg[2]  is  address  of  value! 

move . 1 

(a7),dl 

Argtl]  to  dl  (DRIVE) 

move . 1 

(a0),d2 

get  value  from  address 

jsr 

_LVOAddBuf fers (a6) 

AddBuffers(dl,d2) 

tst.l 

dO 

test  result  (error=0) 

bne.s 

_AvailBuf fer 

if  no  error 

;  Error 

handling  for  RDArgs 

structure 

_OutputError 
bsr.s   _Zerror  ; output  message 

bra . s   _RDArgsFree  ; FreeArgs . . . 

***********************<par^_g>*************************** 

Once  the  initialization  is  complete,  we  can  be  sure  that  no  serious  errors 
have  occurred.  Therefore,  the  return  value  (which  was  stored  in  D4)  can 
be  set  to  'no  error'.  Next,  we  check  to  see  if  the  number  of  buffers  must  be 
changed  before  we  retrieve  the  number.  The  first  argument  is  the  address 
of  the  drive  name,  which  can  be  placed  directly  to  Dl.  Since  this 
argument  is  required  (/A),  we  don't  have  to  check  for  its  presence. 

WARNING:  To  distinguish  between  a  value  of  0  and  a  missing  argument, 
numerical  values  (/N)  require  the  address  of  a  longword  in  the  argument 
field  rather  than  the  value  itself.  The  longword  then  contains  the  actual 
parameter  value. 

This  address  is  moved  to  a  data  register  (DO).  If  the  parameter  is  not 
present,  the  Z  flag  would  have  been  set.  Then  the  address  is  moved  to  an 
address  register  (AO)  in  order  to  obtain  the  actual  value  relative  to  the 
address  register  (D2). 

If  all  of  this  is  successful  or  if  the  buffer  count  was  not  asked  to  be 
changed,  then  the  number  of  buffers  are  displayed.  Otherwise,  an  error 
message  is  output  and  we  jump  to  free  RDArgs. 
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***********************<part_§>* ************* ************* 

Output  number  of  available  buffers 

_AvailBuf fer 

move.l  (a7),dl  ;Arg[l]  to  dl  (DRIVE) 

moveq  #0,d2  ;no  change 

jsr  _LVOAddBuffers(a6)    ;AddBuf fers (dl,d2) 

move.l  d0,4(a7)  ;Arg[2]=Buffers 

bmi.s  _OutputError  ;if  Buffers=-1 

beq.s  _RDArgsFree  ; FreeArgs . . . 

Format  and  output  string 

lea  _FormatString(pc) ,a0  ; format  string 

move.l  aO,dl  ;to  dl  for  call 

move.l  a7,d2  ; field  with  arguments 

jsr  _LVOVPrintf (a6)  ;VPrintf (dl,d2) 

***********************<par(-_7>***  ******************  ****** 

We  go  to  'AvailBuffer'  if  no  change  was  made  to  the  buffer  count  or  after 
the  buffer  count  has  been  changed.  We  only  need  the  drive  name  for 
AddBuffers,  since  the  change  in  indicated  by  0.  The  result  is  stored  as  the 
second  argument  in  our  argument  field.  In  case  of  an  error,  a  message  is 
displayed  or  the  program  is  ended.  VPrintf  is  used  to  output  a  string  to 
CLI.  The  control  codes  of  this  string  have  been  replaced  by  the  entries  of 
the  field  we  want  to  pass.  This  field  is  simply  our  argument  field;  the 
second  entry  of  which  we  have  changed  to  conform  to  our  format  string. 

Now  we  still  have  to  restore  the  system  changes  that  were  made  when 
the  program  was  started.  The  first  thing  to  do  is  free  RDArgs  with 
FreeArgs.  Then  we  restore  the  stack,  which  contains  our  longword  field, 
and  close  the  DOS  library. 

****************** *****<part-7>** ****************** ******* 


**  Free  RDArgs  structure 

** 

_RDArgsFree 
move.l  d6,dl  ; saved  RDArgs 

jsr     _LVOFreeArgs(a6)     ; FreeArgs (dl) 

? 

;  Restore  stack 
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_FreeStack 

addq.l  #8,a7 

addq.l   #8,a7 
** 

**  Close  DOS  library 


; restore  a7 

; (all  16  bytes) 


movea.l  a6,al  ;DosBase  to  al 

movea.l  d5,a6  ;load  ExecBase 

jsr     _LVOCloseLibrary(a6)  ;CloseLibrary (al) 

bra.s   _Programend  ;->end  program 

********************** *<part -8>* ***************** * * * ** * * * * 

The  error  code  that  describes  the  error  of  a  program  ended  with 
RETURN_FAIL  is  entered  in  the  process  structure  for  the  program.  Since 
every  process  begins  with  a  task  structure,  we  can  access  this  structure 
via  ExecBase,  which  always  has  a  pointer  to  the  currently  running  task. 
In  the  following  section,  which  is  used  in  the  case  of  an  OpenLibrary 
error,  the  error  cause  is  sent  to  CLI.  Then  the  program  is  ended.  The 
return  value  is  placed  in  DO  and  the  registers  are  restored.  After  this  are 
the  strings;  you  no  longer  have  to  worry  about  even  or  odd  addresses 
since  no  more  code  follows. 

***********************<part_g>**,**,****»*****4t*1.tittt4<. 


**  Error  opening  DOS  library: 

**  Send  error  cause  to  DOS 

** 

_NotDOS 
moveq    #ERROR_INVALID_RESIDENT_LIBRARY,dO  ;DOS  error  code 

movea.l  ThisTask(a6) ,a0  /Process  structure  for  our  program 

move.l  dO , pr_Result2 (aO)  ; enter  error  cause 


**  End  of  program 

** 

_Programend 
move .1   d4 , dO 
movem.l  (a7)+,d2-d6/a6 
rts 

** 

**  Strings 
** 


; return  code  for  CLI 
/restore  registers 
; return 


_DOSName      dc.b  'dos. library' , 0         ; library  name 
.Template     dc.b  'DRIVE/A, BUFFERS/N' , 0    ; f or  ReadArgs 
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_FormatString  dc.b  'Drive  %s  has  %ld  buffers' ,  10,  0 

************************<gjjp>***************  ******  ******* 

When  you  combine  the  individual  pieces  of  this  program,  you  will  see 
that  things  are  now  much  simpler  than  they  once  were.  Once  assembled, 
a  program  such  as  this  is  less  than  a  half  a  block  long.  Each  program 
requires  at  least  a  FileHeader  block  in  addition  to  this.  So,  you  could 
store  up  to  439  programs  of  this  type  on  a  normal  diskette. 

In  order  to  be  able  to  use  all  mounted  devices  that  may  contain  files,  you 
first  must  obtain  information  about  these  'Drives'.  All  such  devices  are 
included  as  DosEntries  in  the  DosList.  Since  this  list  is  constantly 
updated,  it  used  to  be  necessary  to  turn  off  multitasking  before  searching 
for  a  certain  entry.  Now,  you  can  obtain  access  privileges  with 
LockDosList  in  order  to  prevent  an  update  to  the  list  while  you  are  using 
it.  Let's  take  a  look  at  how  OS  2  retrieves  information  from  this  list: 

**______________========================================** 

**      Retrieve  info  on  all  FileSystem  devices  ** 

** ** 

**  Input:   A6  =  ExecBase                           ** 

**  A5  =  DosBase                            ** 

**  Output:  DO  =  simple  linked  list  of  the  following  ** 

**  structures,  which  can  be  freed  ** 

**  with  exec/FreeVec:                  ** 

STRUCTURE  FileSysDev, 0 

APTR      fsd_Next  ;next  structure 

STRUCT    f sd_InfoData, id_SIZEOF  ; Inf oData  structure 

STRUCT    fsd_Name,36  ;name  buffer 

LABEL     fsd_SIZEOF  ; structure  size 


Register  contents  in  the  routine: 

a6,a5  ExecBase  and  DosBase  (these  are  often  confused) 

a4    DosList  structure 

a3    InfoData  structure 

a2    last  FileSysDev  structure 

a0,al  continuously  changed 

d3 

d6    arg4  for  DosPacket:  0 

d5    arg3  for  DosPacket:  0 
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d4    arg2  for  DosPacket :  0 

d3    argl  for  DosPacket:  BPTR  to  InfoData  structure 

d0-d2  continuously  changed 


.GetFSDevs 

moveq   #0,d0 

movem.l  d0/d2-d6/a2-a4, 

-(a7) 

movea .1  a7 , a2 

moveq    #0,d4 

moveq   #0,d5 

moveq    #0,d6 

InfoData  =  AllocVec ( id_SIZEOF,MEMF_PUBLIC) 


moveq 

#id_SIZEOF,dO 

moveq 

#MEMF_PUBLIC,dl 

jsr 

_LV0AllocVec(a6) 

tst.l 

dO 

beq.s 

. Error 

movea . 1 

d0,a3 

asr  .1 

#2,d0 

move .  1 

d0,d3 

exg 

a5,  a6 

dlist  =  LockDosList(LDF_DEVICES!LDF_READ) 

moveq    #LDF_DEVICES!LDF_READ,dl 
jsr      _LVOLockDosList (a6) 
movea .1  dO , a4 
.Loop 

dlist  =  NextDosEntry (dlist, LDF_DEVICES!LDF_READ) 

move.l   a4,dl 

moveq   #LDF_DEVICES ! LDF_READ , d2 

jsr     _LVONextDosEntry (a6) 

tst.l    dO 

beq.s    .NoMoreEntries 

movea .1  dO , a4 

resl  =  DoPkt(dol_Task,ACTI0N_DISK_INF0,InfoData»2, 0,0,0) 

move . 1  dol_Task (a4 ) , dl 

beq.s  .Loop 

moveq  #ACTION_DISK_INFO,d2 

jsr  _LVODoPkt(a6) 

tst.l  dO 
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beq . s    . Loop 


FileSysDev  =  AllocVec ( f sd_SIZEOF, 

moveq 

#fsd_SIZEOF,dO 

move . 1 

#MEMF_CLEAR  !MEMF_PUBLIC,  dl 

exg 

a5,a6 

jsr 

_LV0AllocVec(a6) 

exg 

a5,a6 

move . 1 

dO, (a2) 

beq.s 

.NoMoreEntries 

movea . 1 

d0,a2 

lea 

fsd_InfoData(a2) ,al 

movea . 1 

a3,a0 

moveq 

#8,d0 

CopylD 

move . 1 

(a0)+, (al)  + 

dbra 

dO, .Copy ID 

movea . 1 

dol_Name (a4 )  ,  aO 

adda . 1 

aO,aO 

adda . 1 

aO,aO 

move . b 

(aO)+,dO 

moveq 

#34, dl 

CopyBSt 

r 

move . b 

(a0)+, (al)+ 

subq.b 

#l,dO 

dble 

dl, . CopyBSt r 

move . b 

#' :', (al) 

bra.s 

.Loop 

NoMoreEntries 

UnLockDosList (LDF_DEVICES ! LDF_READ) 

moveq    #LDF_DEVICES ! LDF_READ, dl 
jsr      _LVOUnLockDosList (a6) 
exg     a5,a6 

FreeVec (InfoData) 

movea. 1  a3,al 
jsr     _LVOFreeVec (a6) 
.Error 

move.l   (a7)+,d0 
movem.l  (a7) +,d2-d6/a2-a4 
rts 


Notice  that  the  drive  names  are  used  here  without  the  colon. 
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About  the  program  flow: 

1.  Get  memory  for  an  InfoData  structure. 

The  memory  block  may  not  be  moved,  it  must  be  allocated  as 
PUBLIC.  The  length  and  contents  do  not  matter.  The  size  must 
correspond  to  that  of  an  InfoData  structure.  We  use  the  new  Exec 
function  Alloc Vec()  here,  which  stores  the  amount  of  memory.  If  a 
value  of  0  is  returned,  the  memory  could  not  be  allocated  and  we 
jump  to  step  6. 

Note:  The  error  cause  can  be  output  with  PrintFault(IoErr(),0). 

2.  Obtain  access  to  DosList  (if  necessary,  include  LDF_VOLUMES 
and/or  LDF.ASSIGNS). 

WARNING  1:  Don't  forget  LDF.READ. 

WARNING  2:  The  UnLockDosList  function  must  be  called  with  the 
same  value. 

WARNING  3:  With  a  reserved  DosList,  do  not  call  functions  that 
must  change  the  DosList. 

WARNING  4:  The  returned  value  is  not  a  DosList  structure  that  can 
be  processed. 

3.  Loop 

3a.  Get  next  DosList  structure  of  the  desired  type.  To  do  this,  either  the 
last  DosList  structure  or  the  value  returned  from  LockDosList  is 
passed  as  the  DosList  structure.  If  a  value  of  0  is  returned,  then  no 
more  entries  of  the  requested  type  are  available  and  we  jump  to  step 
4. 

3b.  The  dol__Task  entry  contains  the  address  of  the  MsgPort  of  the 
FileHandler  process  in  question  (pr_MsgPort).  If  a  value  of  0  is 
found,  then  this  is  not  a  data  storage  device  and  we  jump  to  step  3. 

3c.  We  can  get  the  desired  information  from  the  FileHandler.  In  order  to 
do  this,  we  must  first  create  a  StandardPacket  structure,  load  it  with 
the  proper  information,  send  it  to  the  MsgPort  of  the  FileHandler, 
and  wait  for  an  answer.  The  new  DoPkt  functions  handle  this  for  a 
simple  StandardPacket.  dol_Task,  which  is  the  desired  action 
(ACTION_DISK_INFO),  and  a  BPTR  (address/4)  to  our  InfoData 
structure,  which  is  the  only  packet  parameter,  are  passed  to  the 
DoPkt  function.  If  the  handler  does  not  understand  our  command, 
then  we  are  not  dealing  with  a  data  storage  device,  so  we  jump  to 
step  3. 
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3d.  We  use  AllocVec()  to  reserve  enough  memory  to  hold  the  drive 
name,  the  complete  InfoData  structure,  and  pointers  for  linking  the 
memory  blocks.  If  this  is  unsuccessful,  we  jump  to  step  4. 

3e.  This  memory  block  is  linked  to  the  last  memory  block  allocated  in 
this  way.  We  copy  the  drive  name  and  the  InfoData  structure.  Since 
DOS  does  not  use  colons  with  drive  names,  we  add  it  to  complete 
the  string.  Then  we  jump  back  to  the  start  of  the  loop  (step  3). 

4.  The  DosList  is  set  free. 

WARNING:  You  must  give  the  same  value  used  with  LockDosList. 

5.  The  InfoData  structure  is  set  free.  The  FreeVec()  function  requires 
only  the  start  address  of  its  memory  block. 

6.  End  the  program  and  return  the  list  of  linked  memory  blocks,  that 
must  be  set  free,  with  FreeVec(): 

.loop 

movea.l  dO,al  ; first  structure 

movea.l  (al) ,a2 

jsr     _LVOFreeVec(a6) 

move .1  a2 , dO 

bne . s    . loop 
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3.1.5  The  Exec  Library 


Exec  is  the  base  library  of  the  operating  system.  It  manages  all  other 
libraries,  devices,  resources,  interrupts,  programs,  and  the  system  memory. 
Exec  is  often  called  'Sys',  so  you  may  find  ExecBase  and  SysBase  used 
interchangeably.  The  routines  for  library  management  are  also  integrated 
into  Exec.  The  base  address  of  the  Exec  library  is  stored  in  the  longword 
at  $4.  This  address  must  be  loaded  to  the  A6  register  for  every  function 
call. 


Exec  Library  Functions 

1.  System  Module 

ColdReboot 

FindResident 

InitCode 

InitResident 

InitS  tract 

MakeFunctions 

MakeLibrary 

SumKickData 

2.  Interrupts 

AddlntServer 

Cause 

Disable 

Enable 

Forbid 

GetCC 

Permit 

RemlntServer 

SetlntVector 

SetSR 

Superstate 

Supervisor 

UserState 


3.  Memory  Management 

AddMemList 

AllocAbs 

Allocate 

AllocEntry 

AllocMem 

AllocVec 

AvailMem 

CopyMem 

CopyMemQuick 

Deallocate 

FreeEntry 

FreeMem 

FreeVec 

TypeOfMem 

4.  Structure  Management 

AddHead 

AddTail 

Enqueue 

FindName 

Insert 

RemHead 

Remove 

RemTail 
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5.  Programs 

8.  Devices 

AddTask 

AbortIO 

AllocSignal 

AddDevice 

AllocTrap 

ChecklO 

CacheClearE 

CloseDevice 

CacheClearU 

CreatelORequest 

CacheControl 

DeletelORequest 

FindTask 

DoIO 

FreeSignal 

OpenDevice 

FreeTrap 

RemDevice 

RemTask 

SendIO 

SetExcept 

WaitIO 

SetSignal 

SetTaskPri 

9.  Resources 

Signal 

Wait 

AddResource 

OpenResource 

6.  Communications 

RemResource 

AddPort 

10.  Semaphores 

Alert 

CreateMsgPort 

AddSemaphore 

Debug 

AttemptSemaphore 

DeleteMsgPort 

FindSemaphore 

FindPort 

InitSemaphore 

GetMsg 

ObtainSemaphore 

PutMsg 

ObtainSemaphoreList 

RawDoFmt 

ObtainSemaphoreShared 

RemPort 

Procure 

ReplyMsg 

ReleaseSemaphore 

WaitPort 

ReleaseSemaphoreList 

RemSemaphore 

7.  Libraries 

Vacate 

AddLibrary 

CloseLibrary 

OldOpenLibrary 

OpenLibrary 

RemLibrary 

SetFunction 

SumLibrary 
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Description  of  Functions 

1.  System  Module 

[ColdReboot  Cold  system  reboot! 

Call:  ColdReboot  ( ) 

-726(A6) 

Function:  Resets  the  Amiga  and  all  connected  devices.  This  function 
corresponds  to  pressing  the  (Ictrll  -Amiga-Amiga)  keys 
simultaneously. 

[FindResident  Find  a  system  module] 

Call:  resident  =  FindResident  (name) 

DO  -96 (A6)  Al 

STRUCT  Resident   *resident 
APTR       name 

Function:      Looks  for  a  resident  tag  for  the  given  name. 

Parameters:  name  Address  of  the  name  (RT_NAME). 

Result:  Address  of  the  resident  structure  or  0. 

flnitCode  Initialize  resident  code  module  | 

Call:  lnitCode(startClass,  version) 

-72 (A6)   DO  Dl 

Function:  Initializes  all  resident  modules  of  the  given  type. 
RTF_AFTERDOS  modules  should  have  a  priority  of  less 
than  -100.  Modules  without  a  startClass  value  should  have 
a  priority  of -120. 

Parameters:  startClass    Hags  for  module  type:  RTF_COLDSTART, 

RTFJSDMGLETASK  or  RTF_AFTERDOS. 

version       Version  number 
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UnitResidenT 


Initialize  resident  module  | 


Call:  initResident  (resident,  segList) 

-102 (A6)      Al        Dl 

STRUCT  Resident  *resident 
ULONG  segList 

Function:  Initializes  a  ROMTag.  Normally  jumps  to  the  function 
stored  in  RTJNIT  (A6=ExecBase,  A0=segList,  D0=0). 
However,  if  RTF_AUTOINIT  is  set,  then  RTJNIT  points  to 
four  consecutive  longwords  for  calling  MakeLibrary(). 
These  longwords  contain  the  size  of  the  base  structure, 
table  of  library  functions,  table  for  InitStruct(),  and  the 
RTJNIT  function). 


llnitStruct 


Initialize  a  data  structure  | 


Call:  InitStruct (initTable,  memory,  size) 

-78 (A6)     Al         A2       DO 


STRUCT  InitStruct  *initTable 
APTR   memory 
ULONG  size 

Function:  Deletes  a  data  structure  and  initializes  it  with  the  values  in 
the  given  table.  The  table  can  be  created  with  the 
MACROs  from  "exec/initializers.i". 

Parameters:  initTable     Table  containing  structure  data  (must  end  in  0). 

memory      Address  (even)  of  the  data  structure. 

size  Structure  size  (even  count  of  bytes)  (0=do  not 

delete  first) 


I  MakeFunctions 


Generate  library  vector  table! 


Call: 


tableSize  =  MakeFunctions (target,  functlonArray,  funcDispBase) 
DO  -90 (A6)       A0      Al  A2 

ULONG  tableSize 

APTR  target, f unct ionArray , funcDispBase 
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Function:      Function  for  MakeLibrary().  Used  to  create  a  vector  table 
(negative  base  offsets). 

Parameters:  target  Base  address  of  library/device. 

functionArray 

Table  with  function  addresses  (ending  in  -1)  or 
a  table  'beginning  with  the  Word  -1  containing 
relative  16  bit  offsets  (ending  in  -1). 

funcDispBase 

Address  to  be  added  to  the  relative  16  bit 
values,  or  0. 

Result:  tableSize     Vector  table  size  (for  LIB_NEGSIZE) 

IMakeLibrary  Create  a  library  | 

Call:  library  =  MakeLibrary  (vectors,  structure,  init,  dSize,  segList) 

DO        -84 (A6)      AO       Al         A2     DO     Dl 

STRUCT  Library  'library 
APTR   vectors, init 
STRUCT  InitStruct  'structure 
ULONG  dSize 
BPTR   segList 

Function:      Initializes  a  library  structure. 

Parameters:  vectors       Function  addresses  for  MakeFunctions(). 

structure     Data  for  InitStruct()  or  0. 

init  Library  RTJNIT  routine  or  0. 

dSize  Size  of  base  structure. 

segList       Segment  list  (see  dos/LoadSegO) 
Result:  Library  base  address  or  0. 
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ISumKickData 


Call: 


Calculate  check  sum  across  resident  modules  | 


checksum 

DO 


SumKickData ( ) 
-612 (A6) 


ULONG  checksum 

Function:  Builds  a  check  sum  across  the  linked  list  of  resident 
modules  (KickTagPtr)  and  MemEntry  structures 
(KickMemPtr).  The  check  sum  is  stored  in  KickCheckSum, 
as  long  as  "reset-proof"  changes  to  the  system  will  allow  it. 

Result:  checksum   Value  for  ExecBase->KickCheckSum 


Dec 

Hex 

0 

$0 

2 

$2 

6 

$6 

10 

$A 

11 

$B 

12 

$c 

13 

$D 

14 

$E 

18 

$12 

22 

$16 

26 

$1A 

STRUCTURE  RT, 0 
UWORD  RTJ1ATCHWORD 
APTR   RT_MATCHTAG 
APTR   RT_ENDSKIP 
UBYTE  RT_FLAGS 
UBYTE  RT_VERSION 
UBYTE  RT_TYPE 
BYTE   RT_PRI 
APTR   RT_NAME 
APTR   RT_IDSTRING 
APTR   RT_INIT 
LABEL  RTSIZE 


; residentTag/ROMTag 

; ILLEGAL  command 

; start  of  structure  (RT_MATCHWORD) 

;RT  allowed  starting  with  this  address 

; Flags 

; version 

; module  type  (NT_...) 

.•initialization  priority 

,•  module  name 

; identification  string 

; initialization  routine/data 


RTC_MATCHWORD  =  $4 AFC 


RTB_COLDSTART 
RTB_SINGLETASK 
RTB_AFTERDOS 
RTB_AUTOINIT 


0,  RTF_COLDSTART  =    1  ;Init  from  reset 

1,  RTF_SINGLETASK  =   2  ;task 

2,  RTF_AFTERDOS   =   4  ;Init  after  DOS 
7,  RTF_AUTOINIT   =  $80  ;RT_INIT  =  data 


RTW_NEVER 


;do  not  initialize 


2.  Interrupts 


lAddlntServer 


Insert  an  interrupt  in  a  server  list| 


Call:  AddlntServer (intNum,  interrupt) 

-168 (A6)      DO      Al 


ULONG  intNum 
STRUCT  IS  * interrupt 
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Function:  Links  an  IS  structure  in  a  server  list  of  an  interrupt  server. 
The  given  interrupt  number  is  the  number  of  an  Amiga 
interrupt  source,  not  that  of  a  processor  interrupt.  The 
interrupt  routines  must  end  with  RTS  and  must  set  the 
processor's  Z  flag  if  other  interrupt  routines  are  to  be 
processed.  The  function  is  called  with  IS_DATA  in  Al. 


Parameters:  intNum 


Interrupt  source  with  a  server  (PORTS,  COPER, 
VERTB,  EXTER  or  NM). 


interrupt     IS  structure 

Warning:  Not  suitable  for  high-level  languages.  For  VERTB,  the 
value  $DFF000  must  remain  in  the  AO  register  if  the 
interrupt  has  a  priority  of  10  or  greater. 

See  also:       RemIntServer(),  SetIntVector(),  hardware/intbits.i 

Example:  Linking  an  interrupt  that  is  executed  with  every  vertical 
blank  of  the  monitor. 


_Interrupt_link 
movea.l  $4.w,a6 
lea     _VertBIS(pc),al 
moveq   # INTB_VERTB , dO 
jsr     _LVOAddIntServer (a6) 


_Interrupt_remove 
movea.l  $4.w,a6 
lea     _VertBIS(pc),al 
moveq   # INTB_VERTB , dO 
jsr     _LVORemIntServer (a6) 


JVertBIS 
dc . 1     0,0  ; LN_SUCC , LN_PRED 

dc.b    NT_INTERRUPT, 127  ;LN_TYPE,LN_PRI 
del    _VertBName       ;LN_NAME 
dc . 1    _Data , .Interrupt  ; IS_DATA, IS_CODE 
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**       Interrupt  Routine  ** 

** tir 

**       Input:  aO  =  _Custom  ($dff000)  ** 

**  al  =  _Data    (IS_DATA)  ** 

**       Output:d0,cc  =  0,Z  ** 

**===========================================- . ** 


_Interrupt 
movem.l  d2-d6/a0-a6, -(a7) 

movem.l  (a7)+,d2-d6/a0-a6 

moveq   #0,d0 

rts 

_Data      ;data  block  for  the  interrupt  routine 

[Cause  Calls  a  software  interrupt  I 

Call:  Cause  ( interrupt ) 

-180 (A6)    Al 

STRUCT   IS   * interrupt 

Function:      Executes  a  software  interrupt. 

Parameters:  interrupt     IS  structure  of  the  interrupt. 

[Disable  Turn  off  interrupts  | 

Call:  Disable  ( ) 

-120(A6) 

Function:  Turns  off  all  interrupts  along  with  multitasking.  This  can  be 
a  nested  call. 

Warning:  Essential  operating  system  functions  can  be  destroyed  by 
turning  the  interrupts  off  for  more  than  0.00025  seconds. 
It's  best  to  let  these  calls  go  through  other  operating  system 
functions. 

Wait()   calls    within    a   Disable()/Enable()   call   turn 
multitasking  back  on  until  signaled. 
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[Enable 


Allow  interrupts! 


Call:  Enable  ( ) 

-126 (A6) 

Function:  Reverses  the  effect  of  Disable().  Interrupt  processing  is 
restored  as  long  as  the  number  of  Enable()  calls  correspond 
to  the  number  of  preceding  DisableQ  calls. 


|  Forbid 


Turn  off  multitasking] 


Call:  Forbid  ( ) 

-132 (A6) 

Function:     Turns  off  multitasking  capabilities.  Forbid()  calls  can  be 
nested. 

Warning:      Wait()  calls  within  a  Forbid()/Permit()  call  turn  multitasking 
back  on  until  signaled. 

See  also:       PermitO 


IGetCC 


Retrieve  CCR  in  CPU-compatible  format! 


Call:  conditions  =  GetCCO 

DO  -528 (A6) 


UWORD  conditions 

Function:  "MOVE  SR,<ea>"  is  only  allowed  on  the  68000  in  user 
mode.  This  function  replaces  that  command  so  that  all 
processors  can  read  the  status  register. 

Result:  The  680x0  ConditionCodes 


|  Permit 


Turn  multitasking  back  on| 


Call: 


Permit ( ) 
-138 (A6) 
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Function:  Allows  multitasking  again.  Multitasking  is  restored  as  long 
as  the  number  of  Permit()  calls  correspond  to  the  number  of 
preceding  Forbid()  calls. 

See  also:       Forbid() 

|  RemlntServer  Remove  IS  from  a  server  list  | 

Call:  RemlntServer (intNum,    interrupt) 

-174 (A6)  DO  Al 

ULONG     intNum 
STRUCT  IS   * interrupt 

Function :     Opposite  of  AddIntServer(). 

Parameters:  intNum       Interrupt  source,  as  with  AddIntServer(). 

interrupt     IS  structure,  as  with  AddIntServer(). 

|  Setlnt Vector  Set  interrupt  handler | 

Call:  oldlnterrupt  =  Set Int Vector (intNumber,  interrupt) 

DO  -162 (A6)      DO  Al 

STRUCT  IS  "oldlnterrupt, * interrupt 
ULONG   intNumber 

Function:  Assigns  a  handler  to  an  interrupt  source.  The  previous 
handler  for  this  source  is  removed  and  returned  to  its  IS 
structure.  The  routine,  which  must  end  with  RTS,  contains 
an  AND  combination  of  intenar  and  intreqr  in  Dl,  the 
address  of  the  custom  chip  in  AO,  and  IS_DATA  in  Al. 

Parameters:  intNum       Interrupt  source  with  no  server. 

interrupt     IS  structure  of  the  handler. 

Result:  IS  structure  of  the  previous  handler. 

See  also:       AddIntServer(),exec/interrupts.i,exec/hardware.i 
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jSetSR  Read  and  change  status  register | 

Call:  oldSR  =  SetSR(newSR,   mask) 

DO  -144 (A6)    DO      Dl 

ULONG  oldSR,newSR,mask 

Function:      Reads  the  SR  according  to  the  installed  processor  and  sets 
the  bits  in  a  given  bit  mask  according  to  the  passed  values. 

Parameters:  newSR       Condition  to  which  the  bits  will  be  changed. 

mask  Bit  mask  containing  the  bits  to  be  changed. 

Result:  The  complete  status  register  prior  to  the  change. 

**       Read  status  register  ** 

movea.l  $4.w,a6 

moveq  #0,d0 

moveq  #0,dl 

jsr  _LVOSetSR(a6) 

move .  w  dO ,  . .  . 

**       Set  interrupt  level  4  ** 


**_ 


_*• 


movea.l  $4.w, a6 
move.w  #$400, dO 
move.w  #$700, dl 
jsr     _LVOSetSR(a6) 
move.w  dO, . . . 


I  Superstate  C  hange  processor  to  supervisor  mode  | 


Call:  oldSysStack  =  Superstate  ( ) 

DO  -150 (A6) 

APTR  oldSysStack 
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Function:     Switches  the  processor  to  supervisor  mode.  Keeps  the  user 
stack,  which  contains  all  interrupt  data. 

Result:  Address  of  the  system  stack  or  0  (called  from  supervisor 

mode). 

See  also:       UserState(),  Supervisor() 

|  Supervisor 


Call:  result  =  Supervisor  (userFunc) 

Rx  -30 (A6)  A5 


Execute  routine  in  supervisor  model 


Function:      Executes  an  Assembler  routine  ending  with  RTE  in 
supervisor  mode.  The  registers  are  not  changed. 

Parameters:  userFunc    Address  of  the  Assembler  routine  (RTE). 

Result:  All  register  changes  during  the  execution  of  the  routine  (up 

to  15  changes). 

See  also:       SuperState(),  UserState() 

Example:      Get  the  location  of  the  exception  vector  table  for  higher 
processors: 


movea.l  $4.w,a6 

moveq    #AFF_68010 !AFF_68020 !AFF_68030 !AFF_68040,d7 
and.w   AttnFlags(a6) ,d7 
beq . s   _TableFound 
lea     _Exception(pc) ,a5 
jsr     _LVOSupervisor(a6) 
JTableFound 


.Exception 

moved  vbr,d7  ;VBR  nach  d7 
rte 


lUserState 


Return  processor  to  user  mode] 


Call:  Userstate(sysstack) 

-156 (A6)      DO 
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APTR  sysStack 
Function:      Switches  the  processor  back  to  user  mode. 
Parameters:  sysStack     Supervisor  stack  from  SuperState(). 
See  also:       SuperStateQ,  SupervisorQ 


Dec 

Hex 

STRUCTURE  ExecBase,LIB_SIZE 

34 

$22 

UWORD 

SoftVer 

36 

$24 

WORD 

LowMemChkSum 

38 

$26 

ULONG 

ChkBase 

42 

$2A 

APTR 

ColdCapture 

46 

$2E  APTR 

CoolCapture 

50 

$32 

APTR 

WarmCapture 

54 

$36 

APTR 

SysStkUpper 

58 

$3A 

APTR 

SysStkLower 

62 

$3E 

ULONG 

MaxLocMem 

66 

$42 

APTR 

DebugEntry 

70 

$46 

APTR 

DebugData 

74 

$4A 

APTR 

AlertData 

78 

$4E 

APTR 

MaxExtMem 

82 

$52 

WORD 

ChkSum 

84 

$54 

LABEL 

IntVects 

84 

$54 

STRUCT 

IVTBE, IV_SIZE 

96 

$60 

STRUCT 

IVDSKBLK, IV_SIZE 

108 

$6C 

STRUCT 

IVSOFTINT,  IV_SIZE 

120 

$78 

STRUCT 

IVPORTS,IV_SIZE 

132 

$84 

STRUCT 

IVCOPER, IV_SIZE 

144 

$90 

STRUCT 

IWERTB,  IV_SIZE 

156 

$9C 

STRUCT 

IVBLIT, IV_SIZE 

168 

$A8 

STRUCT 

IVAUD0,IV_SIZE 

180 

$B4 

STRUCT 

IVAUD1,IV_SIZE 

192 

$C0 

STRUCT 

IVAUD2,IV_SIZE 

204 

$CC 

STRUCT 

IVAUD3,IV_SIZE 

216 

$D8 

STRUCT 

IVRBF, IV_SIZE 

228 

$E4 

STRUCT 

IVDSKSYNC,  IV_SIZE 

240 

$F0 

STRUCT 

IVEXTER, IV_SIZE 

252 

$FC 

STRUCT 

IVINTEN,  IV_SIZE 

264 

$108 

STRUCT 

IVNMI,IV_SIZE 

276 

$114 

APTR 

ThisTask 

280 

$118 

ULONG 

IdleCount 

284 

$11C 

ULONG 

DispCount 

288 

$120 

UWORD 

Quantum 

290 

$122 

UWORD 

Elapsed 

Exec  base  structure 

Kickstart  version 

trap  vector  check  sum 

inverted  base  address 

cold  boot  vector 

reset  vector 

warm  boot  vector 

system  stack  upper  limit 

system  stack  lower  limit 

size  of  chip  memory 

global  debugger 

debugger  data 

alarm  data 

FastRAM 

check  sum  up  to  this  point 

interrupt  vectors 

serial  output 

DiskDMA  finished 

software  interrupt 

CIA  interrupts 

copper  interrupt 

vertical  blank 

blitter  finished 

start  of  sound  channel  0 

start  of  sound  channel  1 

start  of  sound  channel  2 

start  of  sound  channel  3 

serial  input 

DiskDMA  synchronized 

external  interrupt 

level  6  interrupt 

level  7  interrupt 

currently  running  program 

wait  counter 

dispatch  counter 

time  period 

elapsed  time 
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292  $124  UWORD  SysFlags 

294  $126  BYTE    IDNestCnt 

295  $127  BYTE    TDNestCnt 

296  $128  UWORD  AttnFlags 
298  $12A  UWORD  AttnResched 
3  00  $12C  APTR   ResModules 
304  $130  APTR   TaskTrapCode 
308  $134  APTR   TaskExceptCode 
312  $138  APTR   TaskExitCode 
316  $13C  ULONG  TaskSigAlloc 
320  $140  UWORD   TaskTrapAlloc 
322  $142  STRUCT  MemList, LH_SIZE 

336  $150  STRUCT  ResourceList,LH_SIZE 
350  $15E  STRUCT  DeviceList,LH_SIZE 
364  $16C  STRUCT  IntrList,LH_SIZE 
378  $17A  STRUCT  LibList,LH_SIZE 
392  $188  STRUCT  PortList, LH_SIZE 
406  $196  STRUCT  TaskReady, LH_SIZE 
420  $1A4  STRUCT  TaskWait, LH_SIZE 
434  $1B2  STRUCT  Sof tints, SH_SIZE*5 
514  $202  STRUCT  LastAlert, 4*4 

530  $212  UBYTE  VBlankFrequency 

531  $213  UBYTE   PowerSupplyFrequency 

532  $214  STRUCT  SemaphoreList,LH_SIZE 
546  $222  APTR   KickMemPtr 

550  $226  APTR   KickTagPtr 

554  $22A  APTR   KickCheckSum 

558  $22E  UWORD  ex_Pad0 

560  $230  ULONG  ex_Reserved0 

564  $234  APTR   ex_RamLibPrivate 

568  $238  ULONG   ex_EClockFrequency 

572  $23C  ULONG  ex_CacheControl 

576  $240  ULONG  ex_TaskID 

580  $244  ULONG  ex_PuddleSize 

584  $248  ULONG  ex_PoolThreshold 

588  $24C  STRUCT  ex_PublicPool,MLN_SIZE 

596  $254  APTR   ex_MMULock 

600  $258  STRUCT  ex_Reserved, 12 

612  $264  LABEL   SYSBASESIZE 


internal  Flags 

interrupt  forbid  counter 

multitask  forbid  counter 

special  system  Flags 

execution  Flags 

ROMTags 

standard  trap  handler 

standard  exception  handler 

standard  return  address 

system  signal  mask 

system  trap  task 

free  memory  PRIVATE! 

Resources   PRIVATE ! 

Devices    PRIVATE ! 

Interrupts  PRIVATE! 

Libraries   PRIVATE! 

MsgPorts   PRIVATE! 

programs   PRIVATE ! 

waiting  tasks  PRIVATE! 

Softwarelnts  PRIVATE! 

last  system  error 

vertical  blank  frequency 

power  supply  frequency 

signal  Semaphores 

reset -protected  memory  blocks 

reset -protected  user  module 

check  sum  across  Mem  and  Tags 


RAM  library  PRIVATE! 

CPU  E  pin  frequency 

CACR 

next  possible  Task 


AFB_68010 
AFB_68020 
AFB_68030 
AFB_68040 
AFB_68881 
AFB_68882 


0,  AFF_68010 

1,  AFF_68020 

2,  AFF_6803  0 

3,  AFF_68040 

4,  AFF_68881 

5,  AFF_68882 


1  ;also  with  68020 

2  ;also  with  68030 
4  ;also  with  68040 
8  ;CPU  68040 

16  ;also  with  68882 
32  ;FPU  68882 
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CACRB_EnableI 

= 

0, 

CACRF_EnableI 

1 

CACRB_FreezeI 

= 

1, 

CACRF_FreezeI 

2 

CACRB_ClearI 

= 

3, 

CACRF_ClearI 

8 

CACRB_IBE 

= 

4, 

CACRF_IBE 

=   16 

CACRB_EnableD 

= 

8, 

CACRF_EnableD 

=  256 

CACRB_Fr ee  z  eD 

= 

9, 

CACRF_FreezeD 

=  512 

CACRB_ClearD 

= 

11, 

CACRF_ClearD 

=2048 

CACRB_DBE 

= 

12, 

CACRF_DBE 

=4096 

/command  cache 

; freeze  command  cache 

; clear  command  cache 

/burst  mode  commands 

;data  cache 

; freeze  data  cache 

; clear  data  cache 

;data  burst 


CACRB_WriteAllocate  =  13,  CACRF_WriteAllocate  =  8192  ;always 

Dec  Hex  STRUCTURE   IS,LN_SIZE  ; Interrupt  Structure 

14   $E  APTR     IS_DATA  ;data  for  IS_CODE 

18  $12  APTR    IS_CODE  ; interrupt  routine 
22  $16  LABEL    IS_SIZE 

Dec  Hex  STRUCTURE   IV, 0  ; Execs  Interrupt  Vectors 

0   $0  APTR    IV_DATA  ;data  for  IS_CODE 

4   $4  APTR    IV_CODE  ; interrupt  Handler/Server 

8   $8  APTR     IV_NODE  ; IS  structure/ 0 
12   $C  LABEL    IV_SIZE 

SB_SAR  =  15,  SF_SAR  =  $8000  ,-execution  plan 
SB_TQE   =  14,  SF_TQE   =  $4000  ;time  exceeded 
SB_SINT  =  13,  SF_SINT  =  $2000  ;SoftInt 

Dec  Hex  STRUCTURE   SH,LH_SIZE  ;SoftInt  Header 
14   $E  UWORD    SH_PAD 
16  $10  LABEL    SH_SIZE 

SIH_PRIMASK  =  $F0  ; priority  mask 
SIH_QUEUES   =5    ; 5  Softlnt  queues 


3.  Memory  Management 
[AddMemList 


Add  memory  to  the  free  memory  list| 


Call:  AddMemList  (  size,  attributes,  pri,  base,  name  ) 

-618 (A6)     DO     Dl  D2    A0     Al 

ULONG  size, attributes 

LONG  pri 

APTR  base, name 

Function:  Adds  a  memory  block  to  the  list  of  free  memory.  A 
MemHeader  structure  is  created  at  the  beginning  of  the 
block. 
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Parameters:  size  Size  of  memory  block, 

attributes    Memory  type 
pri  Allocation  priority 

base  Address 

name  Name  for  memory  or  0 

Attempt  to  allocate  a  certain  memory  block  | 


|  Alloc  Abs~ 


Call:  memoryBlock  =  AllocAbs (byteSize,  location) 

DO  -204 (A6)  DO        Al 

APTR  memoryBlock,  location 
ULONG  byteSize 

Function:  Allocates  a  memory  block  at  a  set  address.  Normally,  this 
routine  is  only  used  by  reset-protected  programs  to  protect 
themselves  from  being  overwritten. 

Parameters:  byteSize     Size 

location      Address 

Result:  Address  of  the  memory  block  (divisible  by  8)  or  0. 


I  Allocate 


Allocate  private  memory  block] 


Call:  memoryBlock=Allocate(memHeader,  byteSize) 

DO  -186 (a6)  A0         DO 

APTR   memoryBlock 

STRUCT  MemHeader  *memHeader 

ULONG  byteSize 

Function:     Assign  a  private  MemHeader  to  a  memory  block. 

Parameters:  memHeader 

Private  MemHeader 
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byteSize      Size  of  the  desired  block. 

Result:  Address  of  the  reserved  memory  block  or  0. 

See  also:       Deallocate,  exec/memory .h 

jAllocEntry  Allocate  several  memory  blocks] 

Call:  memList  =  AllocEntry  (memList) 

DO  -222 (A6)         AO 

STRUCT  MemList   *memList 

Function:     Allocates  all  of  the  blocks  stored  in  a  MemList  structure. 

Parameters:  memList      Structure  containing  MemEntry  structures. 

Result:  New  MemList  structure  with  the  results  (not  identical  to 

the  structure  passed  as  a  parameter).  If  a  block  could  not  be 
allocated,  then  the  memory  type  with  a  matching  bit  31  is 
passed  back  (negative  value). 

|AllocMem  Allocate  memory  [ 

Call:  memoryBlock  =  AllocMem (byteSize,    attributes) 

DO  -198 (A6)    DO  Dl 

APTR     memoryBlock 

ULONG  byteSize, attributes 

Function:      Allocates  the  requested  type  and  amount  of  memory. 

Parameters:  byteSize     Size  of  block 

attributes    Memory  type  (MEMF_„.) 

Result:  Address  of  the  memory  block  or  0. 

Warning:      Memory  that  cannot  be  freed  must  be  MEMF_PUBLIC. 

See  also:      FreeMem() 
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|AllocVec  Allocate  memory  and  store  the  size| 

Call:  memoryBlock  =  AllocVec(byteSize,    attributes) 

DO  -684 (A6)    DO  Dl 

Functions,  Parameters,  Results: 

Same  as  AllocMem(),  except  that  Exec  stores  the  block  size 
for  FreeVec(). 

See  also:       FreeVec(),  AllocMem() 

|  A vailMem  Query  free  memory  | 

Call:  size  =  AvailMem  (attributes) 

DO  -216 (A6)    Dl 

ULONG  size, attributes 

Function:      Query  the  amount  of  free  system  memory. 

Parameters:  requirements 

Memory  type  (MEMF_„.) 

Result:  Number  of  free  bytes  of  the  desired  type.  This  number  may 

not  be  correct  because  of  multitasking. 

|  Copy  Mem  Copy  a  memory  block  | 

Call:  CopyMem(  source,  dest,  size  ) 

-624 (A6)  AO      Al     DO 

APTR  source , dest 
ULONG  size 

Function:      Super-fast  copying  of  a  memory  block. 

Parameters:  source        Source  address 

dest  Destination  address 

size  Block  size  (0  allowed) 
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See  also:       CopyMemQuick() 

ICopyMemQuick  Optimized  memory  copy| 

Call:  CopyMemQuick (   source,    dest,    size   ) 

-630 (A6)  A0  Al  DO 

Function:      Highly  optimized  memory  copying  function. 

Parameters:  source        Source  address  (divisible  by  4) 

dest  Destination  address  (divisible  by  4) 

size  Block  size  (divisible  by  4, 0  allowed) 

See  also:       CopyMem() 

|  Deallocate  Free  memory  block  allocated  with  Allocated 

Call:  Deallocate (memHeader,   memoryBlock,   byteSize) 

-192 (A6)         A0  Al  DO 

STRUCT  MemHeader  *memHeader 
APTR       memoryBlock 
ULONG     byteSize 

Function:     Frees  a  memory  block  that  was  allocated  with  the 
Allocate()  command. 

Parameters:  memHeader 

Own  MemHeader 

memoryBlock 

Address  of  memory  block 

byteSize      Block  size,  0  allowed 

See  also:       AllocateQ,  exec/memory .h 
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IFreeEntry  Free  several  memory  blocks  | 

Call:  FreeEntry  (memList) 

-228 (A6)      AO 

STRUCT  MemList  *memList 

Function:      Frees  all  memory  blocks  in  a  MemList  structure  (result  of 
AllocEntry). 

Parameters:  memList      MemList  structure 

See  also:       AllocEntryO 

IFreeMem  Free  memory  block  | 

Call:  FreeMem(memoryBlock,   byteSize) 

-210 (A6)    Al  DO 

APTR     memoryBlock 
ULONG  byteSize 

Function:      Frees  a  memory  block. 

Parameters:  memoryBlock 

Block  address 

byteSize     Block  size 

See  also:       AllocMem(),AllocAbs() 

IFreeVec  Free  memory  allocated  with  Alloc Vec()| 

Call:  FreeVec  (memoryBlock) 

-690(a6)    Al 

APTR  memoryBlock 

Function:      Frees  a  memory  block  allocated  with  Alloc Vec(). 

Parameters:  memoryBlock 

Result  of  Alloc  Vec()  or  0 
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See  also:       AllocVec() 
ITypeOfMem  ~ 


Get  memory  typej 


Call:  attributes  =  TypeOfMem(  address) 

DO  -534 (A6)      Al 


ULONG  attributes 
APTR     address 

Function:      Queries  the  memory  type  of  the  memory  block  at  the  given 
address  (MEMF_...). 

Parameters:  address       Memory  address 

Result:  Memory  type  or  0  (ROM,  not  linked,  or  does  not  exist). 

Dec  Hex  STRUCTURE  ML,LN_SIZE   ;MemList 
14   $E  UWORD   ML_NUMENTRIES  ;number  of  ME  structures  to  follow 
16  $10  LABEL    ML_ME  ; start  of  the  ME  structures 

16  $10  LABEL   ML_SIZE  =      ;size  excluding  ME  structures 


Dec  Hex  STRUCTURE  ME, 0 


0  $0  LABEL 

0  $0  APTR 

4  $4  ULONG 

8  $8  LABEL 


ME_REQS  = 
ME_ADDR 
ME_LENGTH 
ME_SIZE 


;MemEntry 

/memory  type  for  AllocMemO 
;memory  address  follows 
; block  size 


MEMF_ANY  =  0  ;any  memory  type  (do  not  use!) 

MEMB_PUBLIC  =  0,  MEMF_PUBLIC   =     1  ; usable  memory 

MEMB_CHIP  =   1,  MEMF_CHIP      =      2  ;ChipRAM 

MEMB_FAST  =   2,  MEMF_FAST      =      4  ;FastRAM 

MEMB_LOCAL  =   8,  MEMF_LOCAL     =   $100  ;UserRAM 

MEMB_24BITDMA  =   9,  MEMF_24BITDMA  =   $200  ,-DMA  capable,  24  bit 

MEMB_CLEAR  =  16,  MEMF_CLEAR   =  $10000  ,-delete  beforehand 

MEMB_LARGEST  =  17,  MEMF_LARGEST  =  $20000  /largest  block 

MEMB_REVERSE  =  18,  MEMF_REVERSE  =  $40000  ; inverted 

MEMB_TOTAL  =  19,  MEMF_TOTAL   =  $80000  ; total  size 

MEM_BLOCKSIZE  =  8  ; smallest  available  memory  block 

Dec  Hex  STRUCTURE  MH,LN_SIZE  ; start  of  memory 

14   $E  UWORD   MH_ATTRIBUTES  ; memory  type 

16  $10  APTR    MH_FIRST  ; first  free  block 

20  $14  APTR    MH_LOWER  ;  start  of  block 
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24  $18  APTR    MH_UPPER       ;end  of  block 
28  $1C  ULONG   MH_FREE        ; f ree  bytes 
32  $20  LABEL   MH_SIZE 

Dec  Hex  STRUCTURE  MC,0  ; start  of  a  free  block 
0   $0  APTR    MC_NEXT  ;next  free  block 
4   $4  ULONG    MC_BYTES  ;block  size 
8   $8  LABEL    MC_SIZE 

4.  Structure  Management 

|  Add  Head  Insert  a  node  at  the  start  of  a  list  | 

Call:  AddHeaddist,  node) 

-240 (A6)  A0    Al 

STRUCT  LH  *list 
STRUCT  LN  *node 

Function:     Inserts  a  node  at  the  start  of  a  double  linked  list. 
Parameters:  list  LH  structure  of  the  double  linked  list. 

node  LN  structure  of  the  list  entry. 

|  AddTail  Insert  node  at  the  end  of  a  list| 

Call:  AddTail  (list,  node) 

-246 (A6)  A0    Al 

STRUCT  LH  *list 
STRUCT  LN  *node 

Function:     Like  AddHead(),  but  the  node  is  added  to  the  end  of  the 
double  linked  list. 

Parameters:  list  LH  structure  of  the  double  linked  list. 

node  LN  structure  of  the  list  entry. 
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I  Enqueue  Adds  a  node  to  a  list  | 

Call:  Enqueue  (list,    node ) 

-270 (A6)    A0        Al 

STRUCT  LH  *list 
STRUCT  LN  *node 

Function:  Adds  an  LN  structure  to  a  double  linked  list  using  the 
given  priority  (LN_PRI). 

Parameters:  list  LH  structure  of  the  double  linked  list. 

node  LN  structure  of  the  list  entry. 

I  FindName  Find  a  node  in  a  list  | 

Call:  node  =  FindName  (start,    name) 

D0,CC      -276 (A6)    A0  Al 

STRUCT   LN   *node 
STRUCT   LH   *start 
APTR       name 

Function:  Finds  a  node  with  the  given  name  (LN_NAME)  in  a  double 
linked  list.  In  order  to  find  multiple  nodes  with  the  same 
name,  the  next  call  must  use  the  node  structure  returned 
from  the  previous  call  instead  of  the  ListHeader  structure. 

Parameters:  start  ListHeader  or  ListNode 

name  String  ending  in  0,  containing  node  name. 

Result:  Node  address  or  0. 

|  Insert  Insert  a  node  into  a  list  after  another  node  | 

Call:  Insert  (list,    node,    listNode) 

-234 (A6)    AO      Al  A2 

STRUCT   LH   *list 

STRUCT  LN  *node,*listNode 
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Function:      Inserts  a  node  after  another  node  in  a  double  linked  list. 

Parameters:  list  ListHeader  (if  listNode=0) 

node  ListNode  to  be  inserted. 

listNode      Node  after  which  the  new  node  will  be  inserted 
orO. 

|  RemHead  Remove  the  first  node  in  a  list] 

Call:  node  =  RemHead  (list) 

DO  -258 (A6)    AO 

STRUCT  LN  *node 
STRUCT  LH  *list 

Function:      Gets  the  address  of  the  first  node  in  a  double  linked  list  and 
removes  the  node  from  the  list. 

Parameters:  list  ListHeader  structure 

Result:  Address  of  the  ListNode  or  0  (list  was  empty). 

|  Remove  Remove  a  node  from  a  list] 

Call:  Remove  ( node ) 

-252 (A6)    Al 

STRUCT  LN  *node 

Function:      Takes  the  given  ListNode  out  of  the  list. 

Parameters:  node  ListNode  to  be  removed. 

|  RemTail  Remove  last  node  from  a  list  | 

Call:  node  =  RemTail  (list) 

DO  -264 (A6)    AO 

STRUCT  LN  *node 
STRUCT   LH   *list 
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Function:     Gets  the  address  of  the  last  node  in  a  double  linked  list  and 
removes  the  node  from  the  list. 


Parameters:  list 


ListHeader  structure 


Result:  Address  of  the  ListNode  or  0  (list  was  empty). 


Dec  Hex  STRUCTURE  LH,  0 

0  $0  APTR   LH_HEAD 

4  $4  APTR   LH_TAIL 

8  $8  APTR   LH_TAILPRED 

12  $C  UBYTE  LH_TYPE 

13  $D  UBYTE  LH_pad 

14  $E  LABEL  LH_SIZE 


;list,  ListHeader 
/first  node 
;0  (end  marker) 
; last  node 
;list  type 


Dec  Hex  STRUCTURE  MLH, 0 

0   $0  APTR  MLH_HEAD 

4   $4  APTR  MLH_TAIL 

8   $8  APTR   MLH_TAILPRED 

12   $C  LABEL  MLH_SIZE 


;same  structure,  minimal  configuration 

; first  node 

;0 

; last  node 


Dec  Hex  STRUCTURE  LN,  0  ; ListNode 


0  $0  APTR   LN_SUCC 

4  $4  APTR   LN_PRED 

8  $8  UBYTE  LN_TYPE 

9  $9  BYTE   LN_PRI 
10  $A  APTR   LN_NAME 
14  $E  LABEL  LN_SIZE 


;next  node 

; previous  node 

; node  type 

;node  priority 

;node  name 

;data  begins  here 


Dec  Hex  STRUCTURE  MLN, 0  ;same  structure 

0   $0  APTR  MLN_SUCC  ;next  node 

4   $4  APTR  MLN_PRED  ; previous  node 

8   $8  LABEL  MLN_SIZE  ;data  starts  here 


minimal  configuration 


NT_UNKNOWN 

= 

0 

;not  defined 

NT_TASK 

= 

1 

; Exec  task 

NT_INTERRUPT 

= 

2 

; interrupt 

NT_DEVICE 

= 

3 

; device 

NT_MSGPORT 

= 

4 

,-MP  structure 

NT^MESSAGE 

= 

5 

/message  sent 

NT_FREEMSG 

= 

6 

; message  without  ReplyPort 

NT_REPLYMSG 

= 

7 

/reply  message 

NT_RESOURCE 

= 

8 

/ resource 

NT_LIBRARY 

= 

9 

/library 

NT_MEMORY 

= 

10 

; memory 

NT_SOFTINT 

= 

11 

/software  interrupt 

NT_FONT 

= 

12 

/  font 
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NT_PROCESS 

NT_SEMAPHORE 

NT_SIGNALSEM 

NT_BOOTNODE 

NT_KICKMEM 

NT_GRAPHICS 

NT_DEATHMESSAGE 

NT_USER 

NT_EXTENDED 


=  13  ;AmigaDOS  process 

=  14  /message  semaphore 

=  15  ;SignalSemaphore 

=16  ;boot  node 

=  17  /operating  system  memory 

=  18  ; graphics  data 

=  19  ;end  message 

=254  ;maximum  user  definition 

=255  ; extended  node 


5.  Programs 

|AddTask 


Start  a  program  | 


Call:  AddTask(task,    initialPC,    finalPC) 

-282  (A6)    Al        A2  A3 

STRUCT   TC    *task 

APTR        initialPC, finalPC 

Function:  Adds  a  task  to  the  system,  redistributes  the  processor  time, 
and  starts  the  task  with  the  highest  priority.  Most  of  the 
parameters  are  taken  from  the  initialized  Task  structure  that 
is  passed  to  this  routine.  A  stack  larger  than  256  bytes  is 
needed  for  calling  Exec  functions.  The  minimum  for  other 
operating  system  functions  is  4096  bytes.  The  TC_FLAGS 
are  cleared. 

Parameters:  task  Initialized  TC  structure 

initialPC      Program  start  address 

finalPC       Return  address  or  0  (normal) 

Warning:  Exec  tasks  cannot  use  DOS  routines,  since  these  require  a 
greatly  expanded  Task  structure  (process). 


lAUocSignal 


Allocate  a  signal  bit] 


Call:  signalNum  =  AllocSignal  (signalNum) 

DO  -330 (A6)     DO 

BYTE  signalNum 
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Function:  Allocates  a  free  signal  bit  from  its  own  task.  You  can 
specify  a  certain  bit  or  the  value  -1  if  any  bit  will  do  (this  is 
the  normal  procedure).  Up  to  16  different  bits  can  be 
reserved  per  task.  The  other  bits  are  used  by  the  operating 
system,  for  example,  bit  8  signals  an  incoming  DOS  packet. 

Parameters:  signalNum  Bit  number  (0-31)  or -1  (any  bit) 

Result:  Bit  number  or  - 1  (bit  not  free  or  not  bit  free) 


lAllocTrap 


Allocate  a  CPU  trap  vector 


Call:  trapNum  =  AllocTrap(trapNum) 

DO  -342 (A6)       DO 

LONG  trapNum 

Function:  Gets  the  number  of  a  free  CPU  trap  vector  (TRAP  #).  A 
certain  trap  vector  can  be  specified,  or  -1  can  be  passed  to 
get  the  next  free  vector.  Traps  are  sent  to  the  trap  handler 
in  the  following  format,  which  is  entered  in  tc_TrapCode: 
the  number  of  the  exception  vector  is  on  the  stack  (32-47 
correspond  to  TRAP  #1-#15)  followed  by  the  680x0 
exception  frame. 

Parameters:  trapNum     Trap  number  (0-15)  or -1 

Result:  trapNum     Number  of  the  allocated  trap  vector  (0-15)  or- 1 

(no  free  vector). 


ICacheClearE" 


Clear  cache  memory] 


Call:  CacheClearE (address,    length,    caches) 

-642 (A6)  AO  DO  Dl 

ULONG  length,    caches 
APTR  address 

Function:     Clears  the  internal  command  and  data  cache  memory  of  the 
CPU. 

Parameters:  address       Start  address 
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length         Size  of  block  to  be  cleared,  or  -1  to  clear  all 
addresses. 

caches        The  following  bits  are  supported  at  this  time: 


CACRF_ClearI 
CACRF  ClearD 


Clear  instruction  cache 
Clear  data  cache 


ICacheClearU 


Clear  cache  memory  [ 


Call: 


CacheClearU 
-636 (A6) 


Function:      Clears  all  internal  command  and  data  cache  memory  of  the 
CPU. 


ICacheControl 


Cache  control  in  user  model 


Call:  oldBits  =  CacheControl(cacheBits,cacheMask) 

DO  -648 (A6)  DO  Dl 

ULONG  oldBits, cachBits, cacheMask 

Function:  Global  control  via  the  CACR  register  of  the  68030.  All 
changes  to  the  cache  pertain  to  the  entire  system.  This 
allows  the  programmer  to  turn  off  the  caches  of  programs 
not  normally  executable  (self -modifying  code,  construction 
of  private  vector  tables,  etc.)  and  run  them  with  extremely 
reduced  processor  expenditures. 

Parameters:  cacheBits    New  bit  values  for  the  bits  to  be  changed. 

cacheMask 

Bit  mask  for  the  bits  to  be  changed. 

Result:  The  complete  CACR  register  prior  to  the  manipulation. 

IFindTask 


Find  the  address  of  a  Task  structure  | 


Call:  task  =  FindTask(name) 

DO  -294 (A6)    Al 
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STRUCT  TC  *task 
APTR   name 

Function:  Gets  the  Task  structure  of  the  program  with  the  given 
name.  If  no  name  is  given,  the  routine  reads  ThisTask  from 
the  ExecBase.  Since  tasks  can  also  remove  themselves,  it  is 
usually  necessary  to  turn  off  multitasking. 

Parameters:  name  String  ending  in  0  containing  the  program 

name. 

Result:  Task  control  block,  process,  or  0 

IFreeSignal  Free  a  signal  bit| 

Call:  FreeSignal  (signalNum) 

-336 (A6)        DO 

BYTE  signalNum 

Function:      Free  a  signal  bit  that  was  allocated  with  AllocSignal(). 

Parameters:  signalNum  Bit  number  (0-31)  from  AllocSignal() 

IFreeTrap  Free  a  CPU  trap  vector | 

Call:  FreeTrap  ( trapNum) 

-348 (A6)    DO 

ULONG  trapNum 

Function:     Frees  a  vector  allocated  with  AllocTrap(). 

Parameters:  trapNum     Vector  number  from  AllocTrap(). 

IRemTask  Remove  a  program  | 

Call:  RemTask(task) 

-288 (A6)    Al 

STRUCT   TC    *task 
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Function:  Remove  a  task  from  the  system.  All  linked  MemList 
structures  in  TQMEMENTRY  are  freed  (see  AllocEntryO, 
FreeEntryO). 


Parameters:  task 


Address  of  a  task  control  block  or  0  (task 
removes  itself). 


ISetExcept 


Define  exception  signal  bits] 


Call:  oldsignals  =  SetExcept  (newSignals,  signalMask) 

DO  -312 (A6)   DO  Dl 

ULONG  oldsignals, newSignals, signalMask 

Function:  Sets  the  signal  bits  produced  by  an  exception  processed  by 
the  task  exception  handler  in  tc_ExceptionCode.  The 
handler  is  passed  the  ExecBase  in  A6,  the  contents  of 
tc_ExceptCode  in  Al,  and  the  signal  bits  in  dO.  It  returns  a 
bit  mask  in  which  all  of  the  signal  bits  to  be  reset  are  set. 


Parameters:  newSignals 


New  bit  values  for  the  bits  to  be  changed. 

signalMask 

Mask  with  the  bits  to  be  changed. 

Status  of  the  signal  bits  prior  to  the  reset. 


Result: 
ISetSignal 


Define  task  signal  status  | 


Call: 

Function: 
Parameters: 


Result: 


oldsignals  =  SetSignal (newSignals,  signalMask) 
DO  -306 (A6)   DO  Dl 

ULONG  oldsignals, newSignals, signalMask 

Queries  and  resets  received  signals. 

newSignals 

New  bit  values  for  the  bits  to  be  changed. 

signalMask 

Mask  with  the  bits  to  be  changed. 

Signal  bits  prior  to  the  change. 
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Example: 


**„-,_________________________  ___________________________** 

**       Read  signal  bits  ** 

**. , ** 


movea.l  $4.w,a6 

moveq   #0,d0 

moveq   #0,dl 

jsr     _LVOSetSignal (a6) 

move .1  dO , . . . 

**       Clear  signal  bits  ** 

** ** 


movea.l  $4.w,a6 

moveq  #0,d0 

moveq  #-l,dl 

jsr  _LVOSetSignal(a6) 

move .1  dO , . . . 

**_________________ ======= ============================== ** 

**       Clear  signal  bit  for  CONTROL-C  ** 

**======================================================** 

movea.l  $4.w,a6 

moveq   #0,d0 

move . 1   #SIGBREAKF_CTRL_C , dl 

jsr     _LV0SetSignal(a6) 

move .1  dO , . . . 


|  SetTaskPri  Change  priority  of  a  task  | 

Call:  oldPriority  =  SetTaskPri (task,    priority) 

DO  -300 (A6)         Al  DO 

BYTE       oldPriority 
LONG       priority 
STRUCT   TC    *task 

Function:     Changes  the  priority  of  a  program  and  updates  the 
distribution  of  processor  time  throughout  the  system. 

Parameters:  task  Task  control  block 
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Result: 
|  Signal 


priority       New  priority  (127  to -128) 
Previous  priority 


Sends  a  signal  to  a  program] 


Call:  Signal  (task,    signals) 

-324 (A6)    Al      DO 

STRUCT  TC    *task 
ULONG     signals 

Function:  Sends  the  signal  bits  in  the  given  signal  mask  to  a  task.  If 
the  task  was  waiting  for  one  of  the  signals,  it  is  re-activated 
and  the  processor  time  distribution  is  recalculated. 


Parameters:  task 


Task  control  block 


signals         Signal  mask 


rWait 


Wait  for  a  signal  | 


Call:  signals  =  Wait  (signalSet) 

DO         -318(A6)  DO 

ULONG  signals, signalSet 

Function:     Turns  off  own  task  and  waits  for  one  of  the  given  signal 
bits. 

Parameters:  signalSet     Signal  bit  mask 

Result:  The  received  signal. 


Dec  Hex  STRUCTURE   TC_Struct, LN_SIZE 
14   $E  UBYTE    TC_FLAGS 
TC_STATE 
TC_IDNESTCNT 
TCJTDNESTCNT 
TC_SIGALLOC 
TC_SIGWAIT 
TC_SIGRECVD 
TC_SIGEXCEPT 


15  $F  UBYTE 

16  $10  BYTE 

17  $11  BYTE 

18  $12  ULONG 
22  $16  ULONG 
26  $1A  ULONG 
30  $1E  ULONG 


/previously  TC 

; Flags 

; Status 

/saved  IDNestCnt 

/saved  TDNestCnt 

/allocated  Signalbits 

/expected  Signalbits 

/received  Signalbits 

/signal  for  Exception  Handler 
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34 

$22 

APTR 

tc_ETask 

; extension  structure 

38 

$26 

APTR 

TC_EXCEPTDATA 

;data  for  Exception  Handle: 

42 

$2A 

APTR 

TC_EXCEPTCODE 

/Exception  Handler 

46 

$2E 

APTR 

TC_TRAPDATA 

;data  for  Trap  Handler 

50 

$32 

APTR 

TC_TRAPCODE 

;Trap  Handler 

54 

$36 

APTR 

TC_SPREG 

/StackPointer 

58 

$3A 

APTR 

TC_SPLOWER 

; lower  limit  of  stack 

62 

$3E 

APTR 

TC_SPUPPER 

; upper  limit  of  stack 

66 

$42 

FPTR 

TC_SWITCH 

/routine  task  switch 

70 

$46 

FPTR 

TC_LAUNCH 

/routine  task  start 

74 

$4A 

STRUCT 

TC_MEMENTRY , LH_S I ZE 

/memory  for  task 

88 

$58 

APTR 

TC_Userdata 

/data  for  task 

92 

$5C 

LABEL 

TC_SIZE 

Dec 

Hex 

STRUCTURE  ETask,MN_SIZE 

/task  extension 

20 

$14 

APTR 

et_Parent 

/TC_Struct 

24 

$18 

ULONG 

et_UniqueID 

/task  ID 

28 

$1C 

STRUCT 

et_Children, MLH_SIZE 

/ sub-tasks 

40 

$28 

UWORD 

et_TRAPALLOC 

/allocated  Traps 

42 

$2A 

UWORD 

et_TRAPABLE 

/possible  Traps 

44 

$2C 

ULONG 

et_Resultl 

/ 1 .  result 

48 

$30 

APTR 

et_Result2 

/result  address  (AllocVec 

52 

$34 

STRUCT 

et_TaskMsgPort , MP_SIZE 

1  /TaskPort 

86 

$56 

LABEL 

ETask_SIZEOF 

/not  the  true  size! !  ! 

CHILD_NOTNEW 
CHILD_NOTFOUND 
CHILD_EXITED 
CHILD_ACTIVE 


=  1  /call  to  old  task  (TC) 
=  2  / sub-task  not  found 
=  3  /sub-task  ended 
=  4  /sub-task  active 


TB_PROCTIME 

= 

0, 

TF_PROCTIME  = 

1 

TB_ETASK 

= 

3, 

TF_ETASK 

8 

TB_STACKCHK 

= 

4, 

TF_STACKCHK  = 

$10 

TB_EXCEPT 

= 

5, 

TF_EXCEPT 

$20 

TB_SWITCH 

= 

6, 

TF_SWITCH 

$40 

TB_LAUNCH 

= 

7, 

TF_LAUNCH 

$80 

TS_INVALID 

= 

0 

TS_ADDED 

= 

TS_INVALID+1 

TS_RUN 

= 

TS_ADDED+1 

TS_READY 

= 

TS_RUN+1 

TS_WAIT 

= 

TS_READY+1 

TS_EXCEPT 

= 

TS_WAIT+1 

TS_REMOVED 

= 

TS_EXCEPT+1 

SIGB_ABORT 

= 

0,  SIGF_ABORT 

= 

1 

SIGB_CHILD 

= 

1,  SIGF_CHILD 

= 

2 

SIGB_BLIT 

= 

4,  SIGF_BLIT 

= 

$10 
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SIGB_S INGLE  =  4,  SIGF_S INGLE  =  $10 
SIGB_INTUITION  =  5,  SIGF_INTUITION  =  $20 
SIGB_DOS        =  8,  SIGF_DOS        =  $100 

SYS_SIGALLOC  =  $FFFF  ; system  signal  bits 
SYS_TRAPALLOC  =  $8000  ; system  traps  (TRAP  #15) 

6.  Communications 


|  AddPort  Make  MsgPort  available  to  other  tasks | 

Call:  AddPort  (port ) 

-354 (A6)    Al 

STRUCT  MsgPort  *port 

Function:  Adds  the  given  MsgPort  to  the  system  list  so  that  other 
programs  can  access  it  with  FindPort()  and  address  it. 

Parameters:  port  MessagePort  structure  (LN_NAME  <>  0  if  the 

port  must  be  found  with  FindPort.). 

I  Alert  Indicates  an  error  | 

Call:  Alert  (alertNum) 

-108 (A6)    D7 

ULONG  alertNum 

Function:  Indicates  a  catastrophic  error  (Guru  Meditation). 
Debugging  with  a  second  computer  attached  via  the  serial 
port  is  usually  possible  (9600  baud,  8  bits,  n  parity). 

Parameters:  alertNum     Error  code 

See  also:       exec/alerts.h 

| CreateMsgPort  Create  MP  structure | 

Call:  port  =  CreateMsgPort  ( ) 

dO  -666 (A6) 

STRUCT  MsgPort   *port 
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Function:  Allocates  the  memory  required  for  a  MsgPort  and  initializes 
it.  The  message  queue  list  is  created,  a  signal  bit  is  allocated, 
the  task  is  entered,  and  the  port  is  set  to  PA_SIGNAL  (for 
WaitPortO).  The  port  can  only  be  freed  with 
DeleteMsgPort(). 

Result:  MsgPort  or  0 


|  Debug 


Starts  system  debugger  | 


Call:  Debug  ( f  lags ) 

-114 (A6)    DO 

ULONG    flags 

Function:  Calls  the  system  debugger.  Normally,  this  is  the  "ROM- 
WACK",  but  you  can  also  patch  the  DebugO  function  with 
SetFunction(). 

Parameters:  flags  0  at  this  time 

Free  MP  created  with  CreateMsgPortQI 


IDeleteMsgPort 

Call:  DeleteMsgPort  (msgPort) 

-672 (A6)  aO 

STRUCT  MsgPort    *msgPort 

Function:      Frees  a  MessagePort  created  with  CreateMsgPort(). 

Parameters:  msgPort      MP  structure  from  CreateMsgPort()  orO. 

Find  MsgPort| 


fFlndPort 


Call: 


port  =  FindPort (name) 
DO      -390 (A6)  Al 


STRUCT  MP  *port 
APTR   name 

Function:      Finds  port  in   the  system  list  with   the  given   name 

(LN_NAME). 


195 


3.  Programming  with  AmigaOS  2jc 


Parameters:  name  Port  name  string  ending  in  0. 

Result:  MsgPort  address  or  0 

IGetMsg  Get  next  MessageNode  from  the  port| 

Call:  message  =  GetMsg(port) 

DO  -372 (A6)    AO 

STRUCT  MN  *message 
STRUCT  MP  *port 

Function:  Gets  the  next  message  from  the  port's  queue.  WaitPort()  or 
Wait()  are  used  to  wait  for  messages.  Messages  must  be 
answered  with  ReplyMsg().  A  signal  does  not  always 
indicate  a  message  has  arrived,  it  may  also  indicate  several 
messages  have  arrived  (security  prompt). 

Parameters:  port  MessagePort 

Result:  MessageNode  or  0  if  no  message  has  arrived  at  the  port. 

|  PutMsg  Send  a  MessageNode  to  a  port) 

Call:  PutMsg  (port,    message) 

-366 (A6)    AO      Al 

STRUCT  MP   *port 
STRUCT  MN  *message 

Function:  Sends  a  message  to  a  port.  Depending  on  MP_FLAGS,  the 
port  program  is  also  notified. 

Parameters:  port  MP  structure  of  the  destination  port. 

message      MessageNode  to  be  sent. 

|  RawDoFmt  Format  a  string  | 

Call:  RawDoFmt  (FormatString,  DataStream,  PutChProc,  PutChData) 

-522 (A6)  aO  al  a2         a3 
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APTR  FormatString,DataStream,PutChData 
FPTR  PutChProc 

Function:  A  format  string  is  loaded  with  the  given  arguments  (this  is 
the  basis  of  C  routines  such  as  PrintF(),  etc.).  The  arguments 
are  in  word  or  longword  widths.  The  prefix  code  for  an 
argument  is  the  %  character.  To  get  a  %  character  in  the 
result  string,  the  format  string  must  contain  %%.  The  output 
is  sent  to  the  result  buffer  one  character  at  a  time  using  the 
given  Assembler  routine. 

Parameters:  FormatString 

String  with  arguments  in  the  following  format: 

%[flag] [width. limit] [length] type 

flag'-'  Left  justify 

width  Width  of  argument.  If  the  first 

character  is  '0',  the  given  width  to 
the  left  is  filled  with  zeros. 

limit  Maximum  width,  if  the  argument 

is  a  string. 

length  T         Longword,  otherwise  word  (only 
with  numbers). 

type  Argument  type  (in  DataStream): 

b         BSTR(BPTRtoaBCPL 
string) 

d         Decimal  number 

x         Hexadecimal  number 
(characters  0-F  only) 

s         String  address 

c         Individual  character 
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DataStream 

Memory  block  containing  the  values  and/or 
addresses  of  the  arguments  one  after  another. 

PutChProc 

Address  of  an  Assembler  routine  that  writes  a 
character  to  PutChData.  This  routine  receives 
the  character  in  dO  and  PutChData  in  a3.  This 
routine  normally  looks  like  this:  'MOVE.B 
D0,(A3)+  :RTS'.  The  last  character  is  a  0  byte. 

PutChData 

Buffer  for  storing  the  result  string. 

Example:       Format  text  and  output  to  a  RastPort: 


*  * 


Example  (Result:  "reading  cyl  1,  78  to  go") 


movea.l  _RastPort,a2 
lea     _Format,aO 
lea     _Parameter,al 
bsr     _Print 


_Format 
dc.b     '%s  cyl  %d,  %d  to  go',0 
cnop    0 , 2 

_Parameter 
del  _Action 

dew  1 

dew  78 

_Action 

dc.b  ' reading' , 0 

dc.b  'writing' , 0 

dc.b  "ver'ing",0 

_Print 
movem.l  a2-a3/a6, - (a7) 
lea     . PutChar (pc) ,a2 
move.l  a7,-4(a2) 
lea     -100(a7),a7 
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movea . 1 

a7,a3 

moves . 1 

$4 .w,a6 

jsr 

_LVORawDoFmt ( a 6 ) 

movea . 1 

100(a7) ,al 

movea . 1 

a7,a0 

.Loop 

tst.b 

(a3)  + 

bne.s 

.Loop 

subq .  1 

#2,a3 

move .  1 

a3,d0 

sub.  1 

a7,d0 

movea .  1 

_Gf xBase, a6 

jsr 

_LV0Text(a6) 

lea 

100 (a7) ,a7 

movem . 1 

(a7)+,a2-a3/a6 

rts 

.BufferEnd 

del 

0 

. PutChar 

empa . 1 

. Buf ferEnd(pc) ,a3 

beq.s 

.Overflow 

move . b 

dO, (a3)+ 

rts 

.Overflow 

clr.b 

-Ka3) 

IRemPort 


Call:  RemPort  (port! 

-360(A6)    Al 


Remove  a  MessagePort  from  the  system  list] 


STRUCT   MP    *port 

Function:      Removes  a  port  added  with  AddPort()  from  the  list. 
Parameters:  port  MessagePort 


|ReplyMsg~ 


Reply  to  a  message) 


Call:  ReplyMsg  (message) 

-378(a6)    Al 

STRUCT  MN  *message 
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Function:  After  processing  a  message,  this  routine  sends  a 
MessageNode  back  to  the  sender  or  its  port 
(MN.REPLYPORT). 

Parameters:  message      Address  of  the  MessageNode. 

I  WaitPort  Wait  for  a  messagel 


Call: 


message 
DO 


WaitPort (port) 
-384 (A6)  AO 


STRUCT  MN  *message 
STRUCT  MP  *port 

Function:  Turns  off  own  task  and  waits  for  the  receipt  of  one  or  more 
messages  at  the  given  port.  MP_SIGTASK  and 
MP_SIGBIT  must  be  initialized  and  MP_FLAGS  must  be 
settoPA.SIGNAL. 


Parameters:  port 


MsgPort 


Result:  Address  of  the  first  MessageNode  (not  removed  from  the 

port.  Use  GetMsgQ). 


Alarm  Types: 

AT_DeadEnd  =  $80000000  ; reset  after  display 

AT_Recovery  =  $00000000  /recovery  possible 

Alarm  Groups: 

AG_NoMemory  =  $00010000  ;no  memory 

AG_MakeLib  =  $00020000  ; create  library 

AG_OpenLib  =  $00030000  ;open  library 

AG_OpenDev  =  $00040000  ;open  device 

AG_OpenRes  =  $00050000  ;open  resource 

AG_IOError  =  $00060000  ;I/0  error 

AG_NoSignal  =  $00070000  ;no  signal 

AG_BadParm  =  $00080000  ;bad  parameter 

AG_CloseLib  =  $00090000  ,-closed  too  many  times 

AG_CloseDev  =  $000A0000  ,-closed  too  many  times 

AG_ProcCreate  =  $000BQ000  ; create  process 
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Alarm  Objects: 


AO_ExecLib 

AO_GraphlcsLib 

AO_LayersLib 

AO_Intuition 

AO_MathLib 

AO_DOSLib 

AO_RAMLib 

AO_IconLib 

AO_Expans  ionLib 

AO_DiskfontLib 

AO_UtilityLib 

AO_AudioDev 

AO_ConsoleDev 

AO_GamePortDev 

AO_KeyboardDev 

AO_TrackDi  skDev 

AO_TimerDev 

AO_CIARsrc 

AO_DiskRsrc 

AO_MiscRsrc 

AO_BootStrap 

AO_Workbench 

AO_DiskCopy 

AO_GadTools 

AO_Unknown 


$00008001 
$00008002 
$00008003 
$00008004 
$00008005 
$00008007 
$00008008 
$00008009 
$0000800A 
$0000800B 
$0000800C 
$00008010 
$00008011 
$00008012 
$00008013 
$00008014 
$00008015 
$00008020 
$00008021 
$00008022 
$00008030 
$00008031 
$00008032 
:  $00008033 
:  $00008035 


;Exec  Library 
;Gfx  Library 
; Layers  Library 
.•Intuition  Library 
;Math  Library 
;DOS  Library 
;RAM  Library 
;Icon  Library 
/Expansion  Library 
;Diskfont  Library 
,-Utility  Library 
; Audio  Device 
; Console  Device 
;Gameport  Device 
; Keyboard  Device 
;Trackdisk  Device 
; Timer  Device 
;CIAx  Resource 
;Disk  Resource 
;Misc.  Resource 
; Strap 

/Workbench  Library 
;Diskcopy 
;GadTools  Library 
; unknown  object 


Dec  Hex  STRUCTURE  MP,LN_SIZE 


;MsgPort 


14  $E  UBYTE  MP_FLAGS  ; signal  type 

15  $F  UBYTE  MP_SIGBIT  ; signal  bit  number 

16  $10  APTR  MP_SIGTASK         ;task  or  interrupt 
20  $14  STRUCT  MP_MSGLIST,LH_SIZE  ,-message  queue 

34  $22  LABEL  MP_SIZE 

MP_SOFTINT   =  MP_SIGTASK    ; f or  PA_SOFTINT 

PF_ACTION    =  3  ;mask 

PA_SIGNAL    =  0  ; signal  to  task  MP_SIGTASK 

PA_SOFTINT   =  1  ; execute  software  interrupt  MP_SOFTINT 

PA_IGN0RE    =  2  ; ignore 

Dec  Hex  STRUCTURE  MN,LN_SIZE  ,-message 

14   $E  APTR  MN_REPLYPORT   ;MsgPort  for  reply 

18  $12  UWORD  MN_LENGTH      ; total  structure  size 

20  $14  LABEL  MN_SIZE       ;data  begins  here 
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Example: 

RawKeyMapping : 

movea.l  _SysBase,a6 

movea . 1  _Window, a3 

movea . 1  wd_UserPort (a3 ) , dl 

beq . s   _ErrorNoUserPort 

movea.l  dl,a3 

bra .  s   _GetMessage 

_WaitMsg 
moveq   #-l,dO 
jsr     _LV0AllocSignal(a6) 
tst.b   dO 
bmi . s   _GetMessage 

move.b  dl,MP_SIGBIT(a3) 

move.l   ThisTask(a6) ,MP_SIGTASK(a3) 

clr.b   MP_FLAGS(a3) 

movea .1  a3 , aO 

jsr     _LV0WaitPort(a6) 

addq . b  #  PA_IGNORE , MP_FLAGS ( a3 ) 

move . b  MP_SIGBIT ( a3 ) , dO 
jsr     _LVOFreeSignal(a6) 

_GetMessage 
movea .1  a3 , aO 
jsr     _LVOGetMsg(a6) 
tst.l   dO 
beq.s   _WaitMsg 

movea .1  dO , a4 

move.l  im_Class(a4) ,d0 

cmpi.l  #RAWKEY,dO 

beq  _RawKey 


_ErrorNoUserPort 


_RawKey 
movea.l  _KeymapBase,a6 
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lea     -ie_SIZEOF(a7),a7 


movea .  1 

a7,a0 

clr.l 

(aO) 

move .  b 

#IECLASS_RAWKEY, ie_Class (aO) 

clr.b 

ie_SubClass (aO ) 

move . w 

im_Code (a4 ) , ie_Code (aO ) 

move.w 

im_Qualifier(a4) , ie_Qualif ier (aO) 

move .  1 

im_lAddress (a4) , ie_EventAddress (aO) 

lea 

_Buf fer (pc) ,al 

moveq 

#79, dl 

lea 

$0.w,a2 

jsr 

_LVOMapRawKey (a6 ) 

move .  1 

dO , _CharsInBuf f er 

lea 

ie_SIZEOF(a7),a7 

movea. 1  a4,al 

movea . 1  _Sy sBase , a6 

jsr     _LVOReplyMsg ( a6 ) 


_CharsInBuffer 
del    0 


.Buffer 
ds.b    80 


7.  Libraries 

[AddLibrary  Adds  a  library  to  the  system  list| 

Call:  AddLibrary  ( 1  ibrary ) 

-396 (A6)         Al 

STRUCT  Library  *library 

Function:      Makes  a  complete,  initialized  library  available  to  other 
programs.  Also,  calculates  the  check  sum  for  the  library. 

Parameters:  library        Base  address  of  the  library. 
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ICloseLibrary  Close  a  library  | 

Call:  CloseLibrary  (library) 

-414 (A6)  Al 

STRUCT  Library  *library 

Function:  Closes  a  library.  This  is  necessary  in  order  to  free  the 
memory  occupied  by  unused  libraries. 

Parameters:  library         Base  address  of  the  library  or  0. 

I  OldOpenLibrary  For  Kickstart  1.0  compatibility  I 

Call:  library   =   OldOpenLibrary  (libName) 

DO  -408 (A6)  Al 

STRUCT  Library  * library 
APTR   libname 

Function:  This  function  exists  only  to  maintain  compatibility  with 
operating  system  Version  1.0.  It  corresponds  to 
OpenLibrary(libName,0)  and  should  no  longer  be  used. 

IQpenLibrary  Open  a  library! 

Call:  library  =  OpenLibrary (libName,    version) 

DO  -552 (A6)  Al  DO 

STRUCT  Library  * library 
APTR        libName 
ULONG     version 

Function:  Opens  a  library,  gets  the  base  address,  and  prevents  the 
library  from  being  removed  from  memory.  This  function  also 
checks  to  make  sure  that  the  library  has  the  given  minimum 
version  number.  A  value  of  0  will  accept  any  version,  but 
this  should  never  be  used.  Since  there  is  no  documentation 
on  which  operating  system  version  contains  which  library 
versions,  here  is  a  list: 
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(no  longer  supported! ! ! ) 

(no  longer  supported! ! ! ) 

(no  longer  supported! ! ! ) 

(no  longer  supported! ! ! ) 


Kick  ?.?  =  LibVersion  0 

Kick  1.0  =  LibVersion  30 

Kick  1.1  (NTSC)  =  V.  31 

Kick  1.1  (+PAL)  =   V.  32 

Kick  1.2  =  LibVersion  33 

Kick  1.3  =  LibVersion  34 

Kick  1.3  (+A2024)  =   34/35 

Kick  2.0  =  LibVersion  36  (described  in  this  book) 


If  the  library  is  not  in  the  list,  DOS  loads  it  from  disk  (the 
default  directory  is  LIBS:).  Because  of  this,  only  DOS 
processes  can  call  this  function  for  non-resident  libraries.  A 
complete  path  can  also  be  given  instead  of  a  name. 


Parameters:  libName 


Library  name  (+path  if  desired).  Upper  and 
lowercase  letters  are  also  distinguished  in 
paths. 


version       Minimum  version  number 
Result:  Base  address  of  the  library  or  0. 

1  RemLibrary  Attempt  to  delete  a  library  | 


Call:  RemLibrary  ( library) 

-402 (A6)         Al 

STRUCT  Library  *library 

Function:  Calls  the  LIB_EXPUNGE  routine  of  the  given  library.  This 
sets  the  automatic  removal  feature  for  extra  libraries.  The 
library  will  automatically  be  removed  when  it  is  no  longer 
needed. 

Parameters:  library         Base  address  of  the  library. 

Example :    Attempt  to  remove  a  library  from  memory: 


**  Input:  al=LibName 

** 

movea.l  $4.w,a6 

addq.b  #l,TDNestCnt (a6) 
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lea  LibList (a6) ,aO 

j  sr  _LVOFindName (a6 ) 

tst.l  dO 

beq . s  . not  found 

movea .1  dO , al 

jsr     _LVORemLibrary(a6) 

.not found 
subq.b   #l,TDNestCnt(a6) 


|  SetFunction  Divert  a  library  function  | 

Coll:  oldFunc  =  SetFunction  (library,  funcOffset,  funcEntry) 

DO        -420(A6)    Al       AO.W        DO 


APTR   oldFunc, funcEntry 
STRUCT  Library  * library 
LONG   funcOffset 

Function:      Routine  for  patching  operating  system  functions. 
Parameters:  library        Base  address  of  the  library. 

funcOffset  Offset  of  the  routine  (LVO). 

funcEntry    Address  of  the  new  function. 
Result:  Address  of  the  old  function. 

ISumLibrary  Calculate  check  sum  for  a  library  | 

Call:  SumL  ibr  ary  ( 1  ibrary ) 

-426 (A6)         Al 

STRUCT  Library  *library 

Function:  Recalculates  the  check  sum  of  a  library.  If  the  results  does 
not  agree  with  the  given  check  sum  and  the  CHANGED 
flag  is  not  set,  then  the  Alert()  function  is  called. 
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Parameters:  library         Base  address  of  the  library. 


LIB_OPEN    =   -6  ;LVO  open  library 

LIB_CLOSE   =  -12  ;LVO  close  library 

LIB_EXPUNGE  =  -18  ,-LVO  remove  library 

LIB_EXTFUNC  =  -24  ;LVO  future  extension 


Dec  Hex  STRUCTURE  LIB,LN_SIZE 

14  $E  UBYTE  LIB_FLAGS 

15  $F  UBYTE  LIB_pad 

16  $10  UWORD  LIB_NEGSIZE 
18  $12  UWORD  LIB_POSSIZE 
20  $14  UWORD  LIB_VERSION 
22  $16  UWORD  LIB_REVISION 
24  $18  APTR  LIB_IDSTRING 
28  $1C  ULONG  LIB_SUM 

32  $20  UWORD  LIB_OPENCNT 

34  $22  LABEL  LIB_SIZE 


; library  base  structure 
; Flags 

; vector  table  size 
;size  of  base  structure 
; vers ion  number 
.•revision  number 
identification  string 
/check  sum 
/number  of  opens 


LIB _F lags  values: 


LIBB_SUMMING  =  0,  LIBF_SUMMING  = 

LIBB_CHANGED  =  1,  LIBF_CHANGED  = 

LIBB_SUMUSED  =  2,  LIBF_SUMUSED  = 

LIBB_DELEXP   =  3,  LIBF_DELEXP   = 


1  /check  sum  calculation 

2  / library  changed 

4  /calculate  check  sum 
8  /self -removal 


LIBB_EXP0CNT  =  4,  LIBF_EXP0CNT  =  16  /same  for  system 


8.  Devices 


lAbortlO 


Abort  I/O  process! 


Call:  AbortlO(iORequest) 

-480 (A6)  Al 

STRUCT  IORequest  *iORequest 

Function:  Attempts  to  abort  a  currently  running  I/O  process. 
Regardless  of  whether  or  not  this  is  successful,  it  must  use 
WaitIO()  to  wait  for  the  official  end  of  the  process. 

Parameters:  iORequest  IO  structure  of  any  size  (active  or  complete). 
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lAddPevice  Make  a  device  available  to  other  programs  | 

Call:  AddDevice  (device) 

-432 (A6)      Al 

STRUCT  Device   *device 

Function:  Enters  a  fully  initialized  Device  structure  into  the  system 
list. 

Parameters:  device         Base  address  of  the  device. 

|  ChecklO  Check  to  see  if  an  I/O  process  is  completed  | 

Call:  result  =  ChecklO  (iORequest) 

DO  -468 (A6)    Al 

BOOL       result 

STRUCT  IORequest  *iORequest 

Function:  This  function  checks  to  see  if  an  I/O  process  started  with 
SendIO()  is  still  running  or  is  finished.  Even  if  the  process 
has  finished,  WaitIO()  must  be  used  to  wait  for  the  official 
process  end. 

Parameters:  iORequest  10  structure  of  any  size  (active  or  complete). 

Result:  0  if  the  process  is  still  running;  otherwise  the  address  of  the 

10  structure  is  returned. 

ICloseDevice  Close  a  devicel 

Call:  CloseDevice  ( iORequest ) 

-450 (A6)     Al 

STRUCT  IORequest  * iORequest 

Function:     Closes  access  to  a  device  and  the  sub-objects  of  the  device. 

Parameters:  iORequest  10  structure  from  OpenDeviceQ. 
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|  CreatelORequest  Create  IO  structure  1 

Call:  ioReq  =  CreatelORequest (    ioReplyPort,    size   ) 

DO  -654  (A6)  AO  DO 

STRUCT    IORequest    *ioReq 
STRUCT  MsgPort   *ioReplyPort 
ULONG     size 

Function:      Creates  and  initializes  an  10  structure  of  any  size. 

Parameters:  ioReplyPort 

Address  of  a  fully  initialized  MsgPort  (see 
CreateMsgPortO). 

size  Size  of  the  10  structure. 

Result:  IO  structure  or  0  (error). 


DeletelORequest 

Free  an  10  structure  created  with  CreatelORequestQ 


Call:  DeletelORequest  (   ioReq   ) 

-660 (A6)  aO 

STRUCT  IORequest   *ioReq 

Function:     Frees  a  structure  created  with  CreateIORequest(). 

Parameters:  ioReq         Result  form  CreateIORequest()  or  0. 

|DoIO  Execute  I/O  process  | 

Call:  error  =  DoIO(iORequest) 

DO  -456 (A6)    Al 

BYTE       error 

STRUCT  IORequest  *iORequest 

Function:  Transfers  an  10  structure  containing  the  required  data  to  a 
device  which  extracts  the  command  and  executes  it.  This 
function  returns  at  the  end  of  the  process. 
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Parameters:  iORequest  Initialized  10  structure  from  OpenDevice() 

which  was  manually  loaded  with  device- 
specific  data. 

Result:  0  or  a  device-specific  error  code. 

IQpenDevice  Register  access  to  a  device  | 

Call:  error  =  OpenDevice  (devName,  unitNumber,  iORequest,  flags) 

DO      -444  (A6)    AO       DO  Al         Dl 

BYTE   error 

APTR   devName 

ULONG  unitNumber, flags 

STRUCT  IORequest  * iORequest 

Function:  Attempts  to  obtain  access  to  a  device.  The  passed  10 
structure  is  supplied  the  necessary  data  if  it's  successful.  If 
the  device  is  not  in  memory,  it  attempts  to  load  it  from 
(hard)  disk.  Possible  to  specify  a  complete  path. 

Parameters:  devName    Name  of  the  device  (distinguishes  uppercase 

and  lowercase  notation). 

unitNumber 

Number  of  a  subunit  (e.g.,  1-DF1 :)  or  null. 

iORequest  I/O  structure 

flags  Special  information 

Result:  Null  or  error  code. 

Example:      Attempt  to  remove  a  device  from  memory: 


**  Input:  al=DevName 

*• 

movea.l  $4.w,a6 

addq.b  #l,TDNestCnt (a6) 

lea     DeviceList (a6) ,aO 
j  sr     _LVOFindName (a6 ) 
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tst.l   dO 

beq.s    .not found 

movea.l  dO,al 

jsr     _LVORemDevice(a6) 

.not found 
subq.b   #l,TDNestCnt(a6) 


I  RemDevice 


Remove  device! 


Call:  RemDevice  (device) 

-438 (A6)      Al 

STRUCT  Device  *device 

Function:      Attempts  to  initiate  a  device  removing  itself  from  memory. 

Parameters:  device         Base  address  of  the  device. 


ISendIO 


Start  I/O  process  | 


Call:  SendlO(iORequest) 

-462 (A6)    Al 

STRUCT  IORequest   *iORequest 

Function:      Starts  an  I/O  process  without  waiting  for  the  end. 

Parameters:  iORequest  I/O  structure 


IWaitIO 


Wait  for  the  end  of  an  I/O  process  | 


Call:  error  =  WaitIO(  iORequest) 

DO  -474 (A6)    Al 

BYTE        error 

STRUCT  IORequest  * iORequest 

Function:     Waits  for  the  end  of  an  I/O  process  started  with  SendlOQ. 
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Parameters:  iORequest  I/O  structure  (active  or  completed) 
Result:  Null  or  error  code. 


Dec  Hex  STRUCTURE 
34  $22  LABEL 


DD,LIB_SIZE 
DDSIZE 


; Device  structure 


Dec  Hex  STRUCTURE   UNIT,MP_SIZE 

34  $22  UBYTE    UNIT_FLAGS 

35  $23  UBYTE   UNIT_pad 

3  6  $24  UWORD    UNIT_OPENCNT 
38  $26  LABEL    UNIT_SIZE 


;Unit  structure 
; Flags 

; Number  of  openings 


UNITB_ACTIVE  =  0,  UNITF_ACTIVE  =  1  ; working  now 
UNITB_INTASK  =  1,  UNITF_INTASK  =2  ; in  the  device  task 


IOERR_OPENFAIL 

= 

-1  ; Error  opening 

IOERR_ABORTED 

= 

-2  /Process 

aborted 

IOERR_NOCMD 

= 

-3  /Unknown 

command 

IOERR_BADLENGTH 

= 

-4  ; Length 

not  okay 

IOERR_BADADDRESS  = 

-5  /Address 

not  okay 

IOERR_UNITBUSY 

= 

-6  ;Unit  st 

ill  working 

IOERR_SELFTEST 

= 

-7  /Hardware  error 

ERR_OPENDEVICE 

= 

IOERR_OPENFAIL 

Dec  Hex 

STRUCTURE 

I0,MN_SIZE 

;I/0  structure 

20  $14 

APTR 

IO. 

.DEVICE 

/Device  base  address 

24  $18 

APTR 

IO. 

.UNIT 

/Unit  structure 

28  $1C 

UWORD 

10. 

.COMMAND 

/ Command 

30  $1E 

UBYTE 

IO. 

.FLAGS 

/Flags 

31  $1F 

BYTE 

IO. 

.ERROR 

/Error  code 

32  $20 

LABEL 

IO. 

.SIZE 

32  $20 

ULONG 

IO. 

.ACTUAL 

/Moved  bytes  etc. 

36  $24 

ULONG 

IO. 

.LENGTH 

/Length 

40  $28 

APTR 

IO. 

.DATA 

/Data  address 

44  $2C 

ULONG 

IO. 

.OFFSET 

/Offset  for  positioning 

48  $30 

LABEL 

IOSTD_SIZE 

IOB_QUICK  =  0,  I  OF. 

.QUICK  .=  1 

/execute  immediately 

CMD_INVALID  =  0 

;No  command 

CMD_RESET    =  1 

.•reset  device 

CMD_READ     =  2 

;  Read 

CMD_WRITE    =  3 

/Write 

CMD_UPDATE   =  4 

;Write  buffer 

CMD_CLEAR    =  5 

;C1 

ear  buffer 

CMD_STOJ 

=  6 

;Stop 
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CMD_START    =  7  ; Continue 
CMD_FLUSH    =  8  ; Delete  commands 
CMD_NONSTD  =  9  ;  1 .  Device  specific  command 

9.  Resources 


Add  Resource  Make  a  resource  accessible  to  other  programs  | 


Call:  AddResource  ( resource ) 

-486 (A6)  Al 

APTR  resource 

Function:      Adds  a  completely  initialized  resource  to  the  system  list. 

Parameters:  resource      Library  node  of  the  resource. 

IQpenResource  Get  the  base  address  of  a  resource | 

Call:  resource  =  OpenResource(resName) 

DO  -498 (A6)  Al 

APTR  resource, resName 

Function:      Retrieves  the  base  address  of  a  resource. 

Parameters:  resName      Resource  name 

Result:  Base  address  or  0  (error). 


RemResource Attempt  to  remove  a  resource 


Call:  RemResource  ( resource ) 

-492 (A6)  Al 

APTR  resource 

Function:      Attempts  to  initiate  self-removal  of  the  given  resource. 

Parameters:  resource      Base  address  of  the  resource. 
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10.  Semaphores 

[AddSemaphore  Initialize  and  link  semaphore  | 

Call:  AddSemaphore  (signalSemaphore) 

-600 (A6)  Al 

STRUCT  SS   *signalSemaphore 

Function:      Initializes  an  SS  structure  containing  a  name  and  priority 
and  adds  it  to  the  system  list. 

Parameters:  signalSemaphore 

SS  structure 

[AttemptSemaphore  Attempt  to  allocate  a  semaphore  | 

Call:  success  =  AttemptSemaphore (signalSemaphore) 

DO  -576 (A6)  A0 

LONG  success 

STRUCT  SS   *signalSemaphore 

Function:     Attempts  to  allocate  a  semaphore  and  returns  to  the  caller  if 
this  is  not  possible. 

Parameters:  signalSemaphore 

SS  structure 

Result:  0  SS  was  not  free. 

[FindSemaphore  Find  a  semaphore  | 

Call:  signalSemaphore  =  FindSemaphore  (name) 

DO  -594 (A6)  Al 

STRUCT  SS   * signalSemaphore 
APTR       name 

Function:     Attempts  to  find  a  semaphore  with  the  given  name. 
Parameters:  name  Semaphore  name 

Result:  SS  structure  or  0 
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|InitSemaphore  Initialize  signal  semaphore  | 

Call:  InitSemaphore  (signalSemaphore) 

-558 (A6)  AO 

STRUCT  SS   * signalSemaphore 

Function:      Initializes  an  SS  structure. 

Parameters:  signalSemaphore 

Deleted  SS  structure 

IQbtainSemaphore  Obtain  exclusive  access  to  a  semaphore  | 

Call:  ObtainSemaphore (signalSemaphore) 

-564 (A6)  AO 

STRUCT  SS   *signalSemaphore 

Function:      Allocates  an  SS  structure.  If  this  is  not  possible,  the  task  is 
turned  off  until  the  semaphore  is  freed. 

Parameters:  signalSemaphore 

SS  structure 

IQbtainSemaphoreList  Allocate  semaphores  in  a  listj 

Call:  ObtainSemaphoreList  (list) 

-582 (A6)  AO 

STRUCT   LH   *list 

Function:     Allocates  all  semaphores  in  the  list  or  waits  for  them  to  be 
freed. 

Parameters:  list  Semaphore  list 

IQbtainSemaphoreShared  Shared  semaphore  access  | 

Call:  Obtains  emaphoreShared  (signalSemaphore) 

-678 (A6)  aO 

STRUCT  SS   *signalSemaphore 
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Function:      Obtains  shared  access  to  a  semaphore  or  waits  for  it  to  be 
freed. 

Parameters:  signalSemaphore 

SS  structure 

|  Procure  Allocate  message  semaphore  | 

Call:  result  =  Procure  (semaphore,   bidMessage) 

DO  -540 (A6)    A0  Al 

BYTE  result 

STRUCT  Semaphore  * semaphore 

STRUCT  MN  *bidMessage 

Function:      Attempts  to  allocate  a  semaphore. 

Parameters:  semaphore  A  semaphore  MsgPort 

Result:  0  Semaphore  was  not  free. 

IReleaseSemaphore  Free  semaphore  | 

Call:  ReleaseSemaphore (signalSemaphore) 

-570 (A6)  A0 

STRUCT  SS  *signalSemaphore 

Function:     Frees  a  given  semaphore. 

Parameters:  signalSemaphore 

SS  structure 

IReleaseSemaphoreList  Free  a  semaphore  list| 

Call:  ReleaseSemaphoreList  (list) 

-588 (A6)  A0 

STRUCT  LH   *list 

Function:     Frees  a  semaphore  list. 
Parameters:  list  Semaphore  list 
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|  RemSemaphore  Remove  a  semaphore  | 

Call:  RemSemaphore  ( signalSemaphore ) 

-606 (A6)  Al 

STRUCT  SS   * signalSemaphore 

Function:     Removes  a  semaphore  from  its  list. 

Parameters:  signalSemaphore 

SS  structure 

|  Vacate  Free  a  message  semaphore  | 

Call:  Vacate  ( semaphore ) 

-546 (A6)    A0 

STRUCT  Semaphore   * semaphore 

Function:      Frees  a  semaphore. 

Parameters:  semaphore  Semaphore  MsgPort 

Dec  Hex  STRUCTURE   SSR,MLN_SIZE  ; PRIVATE! 

8   $8  APTR     SSR_WAITER 
12   $C  LABEL    SSR_SIZE 

Dec  Hex  STRUCTURE  SS,LN_SIZE  ; SignalSemaphore 

14   $E  WORD  SS_NESTCOUNT  ; number  of  tasks 

16  $10  STRUCT  SS_WAITQUEUE,MLH_SIZE  ;wait  queue 

28  $1C  STRUCT  SS_MULTIPLELINK, SSR_SIZE  ;link 

40  $28  APTR  SS_OWNER  ;Task 

44  $2C  WORD  SS_QUEUECOUNT  ; queued  Tasks 

46  $2E  LABEL  SS_SIZE 

Dec  Hex  STRUCTURE  SM,MP_SIZE  .-Message  semaphore 

34  $22  WORD    SM_BIDS  ; number  of  bids 

36  $24  LABEL   SM_SIZE 

SMLOCKMSG    =  MP_SIGTASK 
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Example  for  Exec  Library 

Exec  has  several  new  functions  that  make  access  to  devices  considerably 
easier.  As  an  example,  let's  take  a  look  at  how  direct  access  to  a  disk 
drive  can  be  programmed: 


**      Direct  access  to  a  floppy  disk  drive  ** 

** ** 

**       Input:    A6  =  ExecBase  ** 

**  A5  =  DosBase  ** 

**  DO  =  Drive  (0...3)  ** 

**       Output:   DO  =  IOEXTTD  ** 

** :=__ -==============================================** 


_GetAccess  movem.l  d2-d5, 
move .1  dO , d5 


•(a7) 


; dr  ive  number 


jsr     _LVOCreateMsgPort (a6) 
move .1   dO , d3 
beq.s    .Error 


;get  port 

; save  address 


movea.l  dO.aO  ;port  to  aO 

moveq    #IOTD_SIZE, dO  ;size  to  dO 

jsr     _LVOCreateIORequest (a6)  ;get  IORequest 

move.l   d0,d4  ;save  address 
beq.s    .Del Port 


lea 

_TDName  (pc)  ,  aO 

; name  to  aO 

move . 1 

d5,d0 

; number  to  dO 

movea . 1 

dO,al 

; IORequest 

moveq 

#0,dl 

;3.5"  disks 

jsr 

_LVOOpenDevice 1 

a6) 

;  open 

tst.l 

dO 

;  error  test 

bne.s 

.DellOReq 

exg 

a5,  a6 

; DosBase  to  a6 

lsl.l 

#8,d5 

; number  «  1  byte 

addi . 1 

tt'DFO: ' ,d5 

;add  string 

clr  .w 

-(a7) 

;end  of  string 

move . 1 

d5,-(a7) 

;move  string 

move . 1 

a7,dl 

; string  to  dl 

jsr 

_LVODeviceProc ( 

a6) 

/Handler  port 

addq . 1 

#6,a7 

; clear  stack 

move . 1 

dO.dl 

;port  to  dl 

beq.s 

. NoDevProc 
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moveq 

#DOSTRUE,d2 

jsr 

_LVOInhibit(a6 

exg 

a5,a6 

tst.l 

dO 

beq.s 

.CloseDev 

move .  1 

d4,d0 

;set  Flag 
; inhibit  access 
;Exec  to  a6 
; error  test 

;IORequest  ->  dO 


.Exit      movem.l  (a7)+,d2-d5 
rts 


. NoDevProc  exg 
. CloseDev  movea . 
jsr 


a5,  a6 
1  d4,al 

_LVOCloseDevice(a6) 


; clean  up 
;end 

;Exec  to  a 6 
; IOReq  to  al 
; close  Dev 


.DellOReq  movea. 1  d4,a0  ; IOReq  to  aO 

jsr      _LVODeleteIORequest(a6)  ; delete  IOReq 


.De 

iPort 

movea . 1 

d3,a0 

;port  to  aO 

jsr 

_LVODeleteMsgPort (a6) 

; delete  port 

moveq 

#0,d0 

;no  result 

bra.s 

.Exit 

;end 

**— 

====== 

_________ 

========================= 

=============** 

*  * 

Free  drive 

*  * 

** 

** 

Input : 

A6  =  ExecBase 

** 

** 

A5  =  DosBase 

** 

** 

Al  =  IORequest 

*  * 

** 

DO  =  Drive  (0.  .  .3) 

*  * 

** 

Output : 

DO  =  Success  (0=Error) 

*  * 

**_ 

====== 

— — 



It-It 

_FreeDrive  movem. 1  d2-d3 , - (a7 ) 
move .1   dO , d3 


; save  drive 


move.l   al,d2  ;save  IOReq 

jsr      _LVOCloseDevice (a6)  ;close  Dev 

movea. 1  d2,a0  ; IOReq  to  aO 

move.l   MN_REPLYPORT(a0) ,d2  ; save  port 

jsr     _LVODeleteIORequest  (a6)  ,-delete  IOReq 

movea. 1  d2,a0  ;port  to  aO 

jsr     _LVODeleteMsgPort (a6)  ;delete  port 


exg  a5,a6 
lsl.l  #8,d3 
addi .1   # ' DFO : ' , d3 


DOS  to  a 6 
number  «  1  byte 
add  string 
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clr.w  -(a7) 

move.l  d3,-(a7) 

move .1  a7 ,  dl 

jsr  _LVODeviceProc(a6) 

addq.l  #6,a7 

move .1  dO , dl 

beq . s  . NoDevProc 

moveq  #D0SFALSE,d2 

jsr  _LVOInhibit(a6) 

.NoDevProc  exg  a5,a6 

tst.l  dO 

movem.l  (a7)+,d2-d3 
rts 


;end  of  string 
;move  string 
; string  to  dl 
; Handler  port 
; clear  stack 
;port  to  dl 


;code  to  free 
;free 

;Exec  to  a6 
;set  CC 
; clean  up 
;end 


_TDName 


dc.b 


' trackdisk. device' , 0 


;DeviceName 


OPT  0+ 

INCLUDE  IncAll.i 


**  NoClick 


While  we  are  working  with  the  trackdisk  device,  here  is  a  program  that 
turns  off  the  annoying  clicking  sound  made  by  an  empty  disk  drive.  This 
program  can  be  started  from  the  CLI/Shell  or  the  Workbench.  It  is  made 
possible  by  a  new  flag  in  the  Unit  structures.  We  will  also  see  an  example 
of  minimum  message  handling  for  Workbench  starts,  especially  at  the  end 
of  the  program,  which  is  responsible  for  freeing  memory  when  the 
program  is  segmented: 


_Startup 
movea.l  $4.w,a6 


; load  ExecBase 


movea . 1  ThisTask (a6 ) , a5 
moveq   #0,d7 
tst.l   pr_CLI(a5) 
bne.s   _CLIstart 


lea 
jsr 
lea 
jsr 
move .1  dO , d7 


pr_MsgPort (a5)  ,aO 
JLVOWaitPort (a6) 
pr_JIsgPort  (a5) ,  aO 
_LV0GetMsg(a6) 


;get  process 
;WbStartup  to  0 
,-test  CLI 
;->if  available 

;ProcessPort 
;wait  for  message 
;ProcessPort 
;get  message 
;save  WbStartup 
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.CLIstart 
cmpi.w   #36,LIB_VERSION(a6) 
blt.s   _ReplyStartup 


; test  OS  2 
;->if  not  OS  2 


jsr     _LVOCreateMsgPort (a6) 

move .1  dO , d6 

beq . s   _ReplyStartup 


; create  MsgPort 
;and  save 
;->if  error 


movea .1  dO , aO 

moveq    #IOSTD_SIZE, dO 

jsr      _LVOCreateIORequest (a6) 

move .1   dO , d5 

beq.s   _delport 


; MsgPort  to  aO 
; structure  size 
;get  IORequest 
;and  save 
;->if  error 


moveq 

#3,d4 

.NoClickLoop 

lea 

_tdname(pc) ,a0 

move . 1 

d4,d0 

movea. 1  d5,al 

moveq 

#0,dl 

jsr 

_LVOOpenDevice (a6 ) 

tst.l 

dO 

bne.s 

_next 

;  4  drives 


; DeviceName 
/drive  number 
; IORequest 
;3.5"  only 
;  open 

; error  test 
;->if  error 


movea. 1  d5,al  ; IORequest 

movea. 1  IO_UNIT(al) , aO  ;get  UnitPort 

ori.b   #TDPF_NOCLICK,TDU_PUBFLAGS(aO)  ;save  Flag 

jsr     _LV0CloseDevice(a6)  ; close  device 


.next 
dbra    d4,_NoClickLoop 


;all  drives 


_delio 

movea. 1  d5,a0 
jsr     _LVODeleteIORequest (a6) 


; IORequest  to  aO 
/delete  IORequest 


_delport 
movea .1  d6 ,  aO 
jsr     JLVODeleteMsgPort (a6) 


;port  to  aO 
/delete  port 


_ReplyStartup 
move .1  d7 , dO 
beq.s   _fromCLI 


;WbStartup  to  dO 
;->if  not  there 


movea .1  dO , al 

j  mp     _LVORep lyMsg ( a  6 ) 


;WbStartup  to  al 
; reply 
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.•Return  to  program  would  lead  to  a  crash.  If  necessary,  turn 
/multitasking  off  first  (it  will  activate  itself  again  after  the 
.•program  ends)  . 

_fromCLI 
rts  ;end  of  program 

_tdname 
dc . b    ' trackdisk . device ' , 0  ; DeviceName 

Cache  Control 

The  68030  uses  internal  memory  to  store  the  last  command  and  the  last 
memory  access  during  the  execution  of  the  command.  This  internal 
memory,  called  a  cache,  can  greatly  speed  up  processing.  If  the  values 
that  the  processor  needs  are  found  in  a  cache,  then  no  more  RAM  access 
is  necessary,  which  with  a  non-multiplexed  bus  in  a  32  bit  architecture  is 
rather  time-consuming.  Normally,  the  processor  does  not  access  the 
memory  block  containing  the  program  code  when  executing  a  command. 
The  separation  of  command  and  data  caches  can  therefore  speed  things 
up  greatly.  Self-modifying  code  must  be  excluded  from  this,  however, 
because  the  changes  would  be  made  in  the  data  cache  and  not  in  the 
command  cache.  The  Amiga's  coprocessors,  the  DMA  chips,  are  another 
problem.  If  one  of  these  manipulates  the  memory,  the  contents  of  the 
caches  do  not  change  and  the  processor  will  be  working  with  the  wrong 
values.  This  could  make  it  necessary  to  turn  off  the  caches  or  delete 
them.  Assembler  programmers  can  use  the  CACR  (CAche  Control 
Register)  and  CAAR  (CAche  Address  Register)  to  delete  individual 
cache  entries,  but  this  is  not  in  conformance  with  the  operating  system. 

Another  way  of  managing  the  caches  is  needed  for  developing  high 
speed  programs.  The  68030  offers  the  ability  to  "freeze"  the  contents  of 
its  caches.  The  contents  of  a  frozen  cache  cannot  be  changed,  but  they 
can  be  read.  This  allows  you  to  freeze  the  cache  of  a  frequently  used 
subroutine  after  you  have  run  it.  General  program  processing  is  a  little 
slower  because  of  this,  but  the  subroutine  will  be  extremely  fast  the  next 
time  it  is  called. 

The  Exec  takes  care  of  managing  and  storing  the  contents  of  the  CACR 
in  our  example: 
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Turn  off  caches 


movea.l  $4.w,a6  ; load  ExecBase 

moveq   #0,d0  ;new  cache  bits  (value=0) 

move.l   #CACRF_EnableI!CACRF_EnableD,dl  ;mask 

jsr     _LVOCacheControl (a6)  ;save  caches 


Activate  caches 


_*  * 
** 

_*  * 


movea.l  $4.w,a6  ; load  ExecBase 

move.l   #CACRF_EnableI!CACRF_EnableD,dO  ;new  cache  bits 
move.l  dO,dl  ;mask 

jsr     _LV0CacheControl(a6)  /activate  caches 


*  *_ 

*  * 

*  *_ 


Turn  off  caches 


movea.l  $4.w,a6  ;load  ExecBase 

moveq   #0,d0  ;new  cache  bits  (value=0) 

move.l   #CACRF_EnableI!CACRF_EnableD,dl  ;mask 

jsr     _LVOCacheControl (a6)  ; lock  caches 


**  Delete  caches  (User  mode)  ** 

** ** 


movea.l  $4.w,a6 

moveq   #-l,dO 

jsr     _LV0CacheClearU(a6) 


load  ExecBase 
both  caches 
delete  caches 
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**  Store  subroutine  in  cache  ** 

** ================================** 


movea.l  $4.w,a6  ;load  ExecBase 

jsr     _VeryWichtigHighTech  ; subroutine 

move.l  #CACRF_FreezeI!CACRF_FreezeD,dO  ;new  cache  bits 
move.l  dO,dl  ;mask 

jsr     _LV0CacheControl(a6)  /freeze  caches 


**  Free  caches  ** 

** .-.---_______________________=__========** 


movea.l  $4.w,a6  ;load  ExecBase 

moveq   #0,d0  ;new  cache  bits 

move.l   #CACRF_FreezeI!CACRF_FreezeD,dl  /mask 
jsr     _LV0CacheControl(a6)  ;free  caches 


Another  problem  can  arise  using  Burst  mode.  If  the  hardware  is  properly 
designed,  the  68030  can  move  16  bytes  from  cache  to  RAM  (or  RAM  to 
cache)  in  only  5  clock  cycles  (=2-1-1-1  burst).  The  data  transfer  is  done 
in  16  byte  steps  and  is  based  on  modulo  16  addresses.  This  is  a  good 
reason  for  keeping  your  data  well-organized,  as  the  C  structures  of  the 
operating  system  are.  The  speed  in  Burst  mode  is  determined  to  a  large 
extent  by  which  memory  chips  are  used.  Dynamic  Nibble  mode  RAM,  as 
used  in  the  ChipMem  region,  will  only  allow  a  4-1-1-1  burst  (7  clock 
cycles).  Also,  if  the  memory  chips  have  added  WaitStates  during  the  last 
three  longword  accesses,  this  can  slow  down  the  processor  even  more, 
since  each  WaitState  costs  two  clock  cycles.  But  regardless  of  the  speed, 
problems  can  still  occur  because  of  DMA  accesses  when  the  data  is 
disorganized.  The  solution  here  involves  CACRF_IBE  and 
CACRF_DBE,  which  can  be  used  to  turn  the  Instruction  burst  and  the 
Data  burst  on  and  off  via  CacheControl. 
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3.1.6  The  Expansion  Library 


The  Expansion  library,  called  "expansion.library"  with  the  OpenLibraryO 
function,  manages  hardware  and  software  expansions  and  the 
configuration  of  the  strap  routines  (for  booting).  As  always,  the  base 
address  must  be  passed  in  A6. 

Functions  of  the  Expansion  Library 

AddBootNode 

AddConfigDev 

AddDosNode 

AllocConfigDev 

AllocExpansionMem 

FindConfigDev 

FreeConfigDev 

FreeExpansionMem 

GetCurrentBinding 

MakeDosNode 

ObtainConfigBinding 

ReleaseConfigBinding 

RemConfigDev 

SetCurrentBinding 

Description  of  the  Routines 

|AddBootNode  Add  a  bootable  device | 

Call:  ok  =  AddBootNode  (  bootPri,  flags,  deviceNode,  configDev  ) 

DO   -36  (A6)      DO       Dl     AO  Al 

BOOL    ok 

BYTE   bootPri 

ULONG  flags 

STRUCT  DeviceNode  *deviceNode 

STRUCT  ConfigDev  *configDev 

Function:      A  logical  AutoBoot  device  is  added  to  the  DOS  list.  If  DOS 
does  not  exist  yet,  the  data  is  stored  in  a  buffer. 
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Parameters,  Results: 

See  AddDosNode(),  the  only  difference  is  that  an 
AutoBoot  requires  a  ConfigDev  structure. 

|  AddConfigDev  Adda  ConfigDev  structure  | 

Call:  AddConfigDev  (   configDev   ) 

-30 (A6)  A0 

STRUCT  ConfigDev  *configDev 

Function:     Adds  the  given  ConfigDev  structure  to  the  system  list. 

Parameters:  configDev  Initialized  ConfigDev  structure 

See  also:       RemConfigDev() 

|AddDosNode  Mounts  a  data  storage  device  | 

Call:  ok  =  AddDosNode(  bootPri,    flags,   deviceNode   ) 

DO         -150 (A6)  DO  Dl  A0 

BOOL        ok 

BYTE    bootPri 

ULONG  flags 

STRUCT  DeviceNode  *deviceNode 

Function:  Adds  a  filesystem  device  to  the  system  list.  If  DOS  is  not 
active  yet,  the  information  is  stored  in  a  buffer.  If  no 
handler  is  given,  the  new  filesystem  automatically  takes 
over  the  management. 

Parameters:  bootPri       AutoBoot  priority  (127  to  -128).  Only  works  if 

the  corresponding  ConfigDev  structure  is  in 
the  system  list. 

flags  ADNF_STARTPROC  (bit  0)  start  handler 

immediately. 

deviceNode 

Initialized  DOS  device  node. 
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Result:  0  Error 

See  also:       MakeDosNode(),  AddBootNode() 

Example:       Add  a  bootable  drive  to  the  system  and  activate  a 
FileHandler: 

movea.l  _ExpansionBase,a6 
lea     _Parms(pc) ,a0 
jsr     _LVOMakeDosNode(a6) 
tst.l   dO 
beq     _Error 

movea .1  dO , aO 

moveq   #0 ,  dO 

moveq    #ADNF_STARTPROC , dl 

j  sr      _LVOAddDosNode ( a6 ) 


.DosNode 

del 

0 

.Parms 

del 

_DOSname ,  _E: 

del 

1,0 

del 

16 

del 

128 

del 

0,2 

del 

1,11 

del 

2,0,0 

del 

0,79 

del 

5,MEMF_CHIP 

del 

$7fffffff 

del 

$fffffffe 

del 

0 

deb 

1  DOS ' , 0 

.DOSname 

deb 

■dfl',0 

;Unit,  Flags 

;Tablesize 

;Longwords  per  block 

/sector  location,  heads 

; sectors  per  block,  blocks  per  track 

;boot  blocks,  unused,  interleave 

; first  and  last  cylinders 

; number  of  buffers,  memory  type 

; maximum  transfer  rate 

;mask 

;boot  priority 

;FileSystem  type 


_ExecName 
deb     ' trackdisk. device'  ,  0 
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1  AHocConfigDev  Allocate  a  ConfigDev  structure  | 

Call:  configDev  =  AHocConfigDev  () 

DO  -48 (A6) 

Function:      Allocates  a  deleted  ConfigDev  structure. 

Result:  ConfigDev  structure  or  0. 

See  also:       FreeConfigDev() 

|AllocExpansionMem  Allocate  expansion  memory | 

Call:  startSlot  =  AllocExpansionMem(  numSlots,  slotOffset  ) 

DO  -54 (A6)  DO        Dl 

Function:      Allocates  the  given  number  of  slots. 
Parameters:  numSlots    Number  of  slots  required. 

slotOffset    Memory  location 
Result:  First  slot  number  or  - 1 . 

See  also:       FreeExpansionMemQ 


IFindConfigDev  Find  appropriate  ConfigDev 


LsClil*  configDev  =  FindConfigDev{  oldConfigDev,   manufacturer,   product   ) 

DO  -72 (A6)  A0  DO  Dl 

STRUCT  ConfigDev  *configDev, 'oldConfigDev 
LONG      manufacturer , product 

Function:  Finds  a  ConfigDev  structure  that  fits  the  given  description. 
In  order  to  be  able  to  test  several  ConfigDev  structures,  the 
previously  retrieved  ConfigDev  can  be  specified.  Values  of 
-1  will  accept  every  manufacturer  code  and  every  product 
ID. 

Parameters:  oldConfigDev 

Last  result  or  0  (start  of  list) 
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manufacturer 

Manufacturer's  code  or  -1 

product       Product  ID  or  - 1 

Result:  The  next  appropriate  ConfigDev  structure  or  0. 

IFreeConfigDev  Free  a  ConfigDev  structure] 

Call:  FreeConfigDev(   configDev  ) 

-84 (A6)  A0 

STRUCT  ConfigDev  *configDev 

Function:      Frees  a  structure  allocated  with  AllocConfigDev(). 

Parameters:  configDev  ConfigDev  structure 

See  also:       AllocConfigDevQ 


IFreeExpansionMem  Free  memory 


Call:  FreeExpansionMem(    startSlot,    numSlots    ) 

-90 (A6)  DO  Dl 

Function:      Frees  memory  allocated  with  AllocExpansionMem(). 

Parameters:  Same  as  with  AllocExpansionMem(). 

See  also:       AllocExpansionMem() 

|  GetCurrentBinding  Gets  a  copy  of  CurrentBinding  | 

Call:  actual  =  GetCurrentBinding  (  CurrentBinding,  size  ) 

DO        -138 (A6)  A0  DO: 16 

Function:      Copies  the  contents  of  the  CurrentBinding  structure  to  the 
given  buffer. 

Parameters:  CurrentBinding 

CurrentBinding  structure 

size  Structure  size 
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Result:  The  true  size  of  the  CurrentBinding  structure 

See  also:       SetCurrentBindingO 
IMakeDosNode 


Create  a  DosList  entry  | 


Call: 


Function: 


deviceNode  =  MakeDosNode (  parameter Pkt  ) 
DO  -144 (A6)     AO 

STRUCT  DeviceNode  *deviceNode 
APTR   parameterPkt 

Creates  all  of  the  data  structures  required  to  add  a  device 
with  AddDosNodeQ. 


Parameters:  parameterPkt 

Longword  field  with  all  the  required 
information: 

Device  name  (DOS,  for  example  "dfl"),  device 
name  (Exec,  for  example  "trackdisk.device"), 
unit  number,  flags  for  OpenDevice(),  number  of 
following  longwords,  environment  table  for  the 
FileHandler. 


Result: 
See  also: 
Example: 

movea.l  _ExpansionBase,a6 
lea     _Parms (pc) , aO 
j  sr     _LVOMakeDosNode ( a  6 ) 
move .  1  dO , _DosNode 


Initialized  structure  or  0. 

AddDosNodeO 

Create  a  DosNode  for  a  3.5"  drive  as  "DF1:": 


_DosNode 

del    0 

_Parms 
dc . 1    _DOSname , _ExecName 
del    1,0         ;Unit,  Flags 
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del  16  ;Table  size 

del  128  ;Longwords  per  block 

del  0,2  ; sector  location,  heads 

del  1,11  ; sectors  per  block,  blocks  per  track 

del  2,0,0  ;boot  blocks,  unused,  interleave 

del  0,79  ; first  and  last  cylinders 

del  5,MEMF_CHIP  ; number  of  buffers,  memory  type 

del  $7fffffff  .-maximum  transfer  rate 

del  $fffffffe  ;mask 

del  0  ;boot  priority 

deb  'DOS',0  ;FileSystem  type 

_D0Sname 
deb     'dfl',0 

_ExecName 
deb    '  trackdisk. device1  ,  0 

[ObtainConfigBinding  Enable  configuration  binding | 

Call:  ObtainConfigBinding  ( ) 

-120 (A6) 

Function:      Obtains  the  approval  to  add  drivers  to  ConfigDev 
structures. 

See  also:       ReleaseConfigBindingO 

[ReleaseConfigBinding  Release  configuration  binding | 

Call:  ReleaseConfigBindingO 

-126(A6) 

Function:      Allows  access  by  other  programs. 
See  also:       ObtainConfigBindingO 


|  RemConfigDev  Remove  a  ConfigDev  from  the  system  list  | 

Call:  RemConfigDev (   configDev  ) 

-108 (A6)  A0 

Function:     Removes  the  given  ConfigDev  structure  from  the  system 
list. 
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Parameters:  configDev  ConfigDev  structure 
See  also:       AddConfigDev() 
|  SetCurrentBinding 


Set  CurrentBinding] 


Call:  SetCurrentBinding)    currentBinding,    size   ) 

-132 (A6)  AO  D0:16 

Function:      Copies  the  contents  of  the  given  buffer  to  the  system's 
CurrentBinding  structure. 

Parameters:  currentBinding 

Buffer    with    the    new    contents    for    the 
CurrentBinding  structure. 


size 


Buffer  size 


See  also:       GetCurrentBindingO 

ADNB_STARTPROC=0,  ADNF_STARTPROC=l  /start  Handler  immediately 

Dec  Hex  STRUCTURE  BootNode, LN_SIZE  ;boot  node 

14   $E  UWORD  bn_Flags  ; Flags 

16  $10  APTR  bn_DeviceNode  ;DosList 
20  $14  LABEL  BootNode_SIZEOF 


Dec  Hex  STRUCTURE  ExpansionBase, LIB_SIZE  ; library 

34  $22  UBYTE   eb_Flags 

35  $23  UBYTE   eb_Private01 

36  $24  ULONG   eb_Private02 
40  $28  ULONG   eb_Private03 

44  $2C  STRUCT  eb_Private04, CurrentBinding_SIZEOF 
60  $3C  STRUCT  eb_Private05, LH_SIZE 
74  $3A  STRUCT  eb_MountList, LH_SIZE  ; BootNodes 
. . .  ;more  private  data. . . 


; readable 
; private 
; private 
/private 
/private 
/private 
private 


EE_OK 

EE_LASTBOARD 

EE_NOEXPANSION 

EE_NOMEMORY 

EE_NOBOARD 

EE_BADMEM 


=  0  /no  errors 

=40  /cannot  be  closed 

=41  /not  enough  memory 

=  42  /no  normal  memory  free 

=  43  /no  board  available 

=  44  /defective  memory 
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EBB_CLOGGED 

0, 

EBF_CLOGGED 

=   1 

; close  error 

EBB_SHORTMEM 

= 

1, 

EBF_SHORTMEM 

=   2 

;less  memory 

EBB_BADMEM 

= 

2, 

EBF_BADMEM 

=   4 

.•defective  memory 

EBB_DOSFLAG 

= 

3, 

EBF_DOSFLAG 

=   8 

,-for  AmigaDOS 

EBB_KICKBACK33 

= 

4, 

EBF_KICKBACK33 

=  16 

;OS  change  (DOS) 

EBB_KICKBACK36 

= 

5, 

EBF_KICKBACK3  6 

=  32 

;OS  change  (DOS) 

3.1 .7  The  GadTools  Library 


The  GadTools  library,  which  uses  the  name  "gadtools.library"  for 
OpenLibraryO,  is  used  to  simplify  the  programming  of  gadgets,  menus, 
and  Intuition  events.  Previous  operating  system  versions  required  many 
data  structures  to  be  created  by  hand.  Now,  an  application  can  be  made 
more  user-friendly  with  just  a  few  calls  to  the  functions  of  the  GadTools 
library. 

GadTools  Library  Functions 

CreateContext 

CreateGadgetA 

CreateMenusA 

DrawBevelBoxA 

FreeGadgets 

FreeMenus 

FreeVisuallnfo 

GetVisuallnfoA 

GTJBeginRefresh 

GT_EndRefresh 

GTFilterlMsg 

GT_GetIMsg 

GT_PostFilterIMsg 

GT_RefreshWindow 

GT_ReplyIMsg 

GT_SetGadgetAttrsA 

LayoutMenuItemsA 

LayoutMenusA 
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Description  of  the  Functions 

ICreateContext  Reserve  a  data  blockl 

Call:  gad  =  CreateContext  (glistpointer) 

DO  -114 (A6)  AO 

STRUCT  Gadget   *gad, **glistpointer 

Function:     Reserves  room  for  the  context  data.  This  function  must  be 
called  before  creating  gadgets  with  the  GadTools  library. 

Parameters:  glistptr       Address  of  a  longword  ending  in  0  where 

GadTools  will  store  the  address  of  the  gadget 
being  generated.  The  gadget  address  can  then 
be  given  to  Intuition  later  (AddGList()  etc.). 

Result:  Address  of  a  context  gadget  or  0. 


ICreateGadgetA  Create  a  GadTools  gadget  I 

Call:  gad  =  CreateGadgetA(kind,  previous,  newgad,  taglist) 

DO     -30 (A6)        DO     AO         Al       A2 

STRUCT  Gadget  *gad, *previous 
ULONG  kind 

STRUCT  NewGadget  *newgad 
STRUCT  Tagltem  *taglist 

Function:  Gets  a  gadget  of  the  given  type,  initializes  it  as  indicated  by 
the  tags  and  the  NewGadget  structure,  and  adds  it  to  an 
existing  gadget. 

Parameters:  kind  Gadget  type 

previous     Gadget  to  which  the  new  GG  will  be  added. 

newgad      NewGadget    structure   that   describes    the 
gadget. 

taglist         Tagltem  field  with  special  instructions. 
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Tags:  GTJJnderscore  (Char  (starting  with  version  37))  defines 

the  character  for  which  the  following  character  will  be 
underlined  in  the  gadget  text  (for  example,  to  indicate  the 
"hotkey"  that  will  activate  the  gadget).  If  the  "_"  character 
is  selected  and  the  gadget  text  reads  "_Color",  then  the 
gadget  text  will  appear  on  screen  with  the  "C"  underlined. 

GA_Disabled  (BOOL)  is  used  to  turn  off  the  gadget 
(TRUE).  By  default,  the  gadget  is  active. 

GTCB_Checked  (BOOL)  is  used  to  display  a  check  mark 
(TRUE)  in  a  Checkbox  gadget.  The  default  is  no  check 
mark. 

GTCY_Labels  (STRPTR  *)  sets  the  O-terminated  string 
address  field  for  Cycle  gadgets. 

GTCY_Active  (UWORD)  sets  the  number  (0...)  of  the 
active  text  for  a  Cycle  gadget.  The  default  string  is  0. 

GTIN_Number  (ULONG)  sets  the  contents  (value)  of  an 
Integer  gadget.  The  default  value  is  0. 

GTIN_MaxChars  (UWORD)  sets  the  maximum  number  of 
decimal  places  for  an  Integer  gadget.  The  default  is  10. 

STRINGA_ExitHelp  (BOOL)  (V37  and  up)  If  TRUE,  an 
Integer  gadget  can  be  ended  by  pressing  the  Help  key. 
You  will  then  get  a  GADGETUP  with  the  RawKey  code  of 
the  Help  key  ($5F). 

GA_TabCycle  (BOOL)  (V37  and  up)  If  TRUE,  pressing 


(Tab)  or  1  shin H Tab)  will  activate  the  next  or  the  previous 
gadget.  The  default  is  TRUE. 

GTLV_Top  (UWORD)  sets  the  number  of  the  first  visible 
entry  in  a  ListView  gadget  (scrollable  list).  The  default  is 
Entry  0. 
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GTLV_Labels  (STRUCT  List  *)  passes  a  list  whose 
LN_NAME  entries  will  appear  in  the  ListView  gadget  (box 
with  scrollable  list). 

GTLV_ReadOnly  (BOOL)  sets  the  read-only  attribute  for  a 
ListView  gadget  (TRUE). 

GTLV_ScrollWidth  (UWORD)  sets  the  width  of  the  scroll 
bar.  The  default  is  16  pixels. 

GTLV_ShowSelected  (STRUCT  Gadget  *)  passes  a  String 
gadget,  in  which  the  selected  entry  can  be  edited,  to  a 
ListView  gadget.  If  the  value  0  is  passed,  the  selected  item 
is  displayed  below  the  ListView  gadget. 

GTLV_Selected  (UWORD)  sets  the  number  of  the  pre- 
selected item  in  a  ListView  gadget.  The  default  is  -1,  which 
means  no  item  is  pre-selected. 

LAYOUTA_Spacing  sets  the  number  of  lines  between  two 
items  in  a  ListView  gadget.  The  default  is  0. 

GTMXLabels  (STRPTR  *)  is  a  0-terminated  string  address 
field  containing  the  texts  that  will  be  displayed  next  to  the 
selection  buttons  in  a  mutually  exclusive  selection  table 
(MutualXclusive  gadget). 

GTMX_Active  (UWORD)  sets  the  active  button  number 
for  an  MX  gadget.  The  default  button  is  0. 

GTMX_Spacing  (UWORD)  sets  the  distance  between  two 
items  in  an  MX  gadget.  The  default  is  one  line  (1). 

GTNM_Number  (LONG)  sets  the  value  to  be  displayed  as  a 
decimal  string  in  a  non-revisable  gadget  (default:  0). 

GTNM_Border  (BOOL)  displays  a  border  (TRUE). 

GTPA_Depth  (UWORD)  sets  the  number  of  bit-planes  for  a 
Palette  gadget.  The  default  is  one  bit-plane  (2A1  colors). 
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GTPA_Color  (UBYTE)  sets  the  default  for  the  selected 
color  of  a  Palette  gadget  (otherwise  1  is  used). 

GTPA_ColorOffset  (UBYTE)  determines  the  number  of  the 
first  color  to  be  queried  in  a  Palette  gadget.  The  default  is 
color  0. 

GTPAJndicatorWidth  (UWORD)  sets  the  width  of  the 
palette's  color  indicator  if  it  is  used. 

GTPAJndicatorHeight  (UWORD)  is  the  same  for  the 
height  of  the  color  indicator. 

GTSCJTop  (WORD)  sets  the  start  of  a  ScrollGadget  (similar 
to  the  old  PropGadget).  The  default  is  0. 

GTSC_Total  (WORD)  sets  the  number  of  available  units 
(ScrollGadget,  default:  0  units). 

GTSCJVisible  (WORD)  sets  how  many  units  will  be  visible 
at  once  (ScrollGadget,  default:  2  units  from  GTSC_Total). 

GTSC_Arrows  (UWORD)  equips  the  ScrollGadget  with 
arrow  symbols.  The  value  defines  the  height  of  the  arrow 
and  ScrollGadget  for  a  horizontal  gadget  and  the  width  of 
the  arrow  and  Scroll  Gadget  for  a  vertical  gadget. 

PGA_Freedom  is  used  to  define  a  vertical  ScrollGadget 
(LORIENTJVERT).  The  default  is  a  horizontal 
ScrollGadget  (LORffiNTHORIZ). 

GA_Immediate  (BOOL)  causes  every 
IDCMP_GADGETDOWN  event  to  be  passed  (TRUE). 

GA_RelVerify  (BOOL)  same  for  IDCMP_GADGETUP 
events. 

GTSL_Min  (WORD)  sets  the  minimum  value  for  a 
SliderGadget  (default:  0). 
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GTSL_Max  (WORD)  is  the  same  for  the  maximum  value 
(default:  15). 

GTSL_Level  (WORD)  sets  a  SliderGadget  to  a  specified 
location  (default  0). 

GTSL_MaxLevelLen  (UWORD)  sets  the  maximum  length 
of  the  string  containing  the  location  for  the  SliderGadget. 

GTSL_LevelFormat  (STRPTR)  determines  a  format  string 
for  the  32  bit  value  indicating  the  location  for  the 
SliderGadget.  The  format  string  is  formatted  with  the  Exec 
routine  RawDoFmt(). 

GTSL_LevelPlace  determines  where  the  position  value  will 
be  output  (PLACETEXT_LEFT  (default), 
PLACETEXT_RIGHT,  PLACETEXT_ABOVE,  or 
PLACETEXT.BELOW). 

GTSL_DispFunc  (FPTR)  associates  a  function  with  a 
SliderGadget.  The  function  is  passed  the  gadget  address 
and  position  value  on  the  stack.  The  slider  position  is 
calculated  from  this  information  and  passed  back  as  a 
longword  in  DO. 

GTSTJString  (STRPTR)  sets  the  string  used  to  initialize  the 
contents  of  a  StringGadget  (default:  empty  =  0). 

GTST_MaxChars  (UWORD)  sets  the  maximum  number  of 
characters  in  a  StringGadget  buffer. 

GTTXJText  (STRPTR)  sets  the  contents  of  a  TextGadget 
(default:  empty=0). 

GTTX_CopyText  (BOOL)  causes  the  TextGadget  to  make 
a  copy  of  GTTXJText  (TRUE). 

GTTX_Border  (BOOL)  makes  a  border  for  the  TextGadget 
(TRUE). 

Result:  Address  of  a  new  gadget  or  0. 
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|  CreateMenus A  Create  a  GadTools  menu  | 

Call:  menu  =  CreateMenusA(newmenu,    taglist) 

DO  -48 (A6)  AO  Al 

STRUCT  Menu   *menu 
STRUCT  NewMenu  *newmenu 
STRUCT  Tagltem  *taglist 

Function:      Creates  a  complete  MenuStrip  according  to  the  information 
in  the  NewMenu  structure  and  the  tags. 

Parameters:  newmenu    List  with  initialized  NewMenu  structure. 

taglist         Tagltem  field 

Tags:  GTMN_FrontPen  (UBYTE)  text  color  (or  else  0). 

GTMN_FullMenu  (BOOL  (Version  37  and  up))  indicates 
that  the  menu  description  of  the  NewMenu  structure 
pertains  to  a  complete  MenuStrip  (TRUE). 

GTMN_SecondaryError  (ULONG  *  (Version  37  and  up)) 
passes  the  address  of  a  long  initialized  to  0,  to  which  an 
error  code  can  be  written: 

GTMENUJNVALID 

Invalid  NewMenu  structure  (result  0). 

GTMENU_TRIMMED 

Too  many  items  (some  are  trimmed). 

GTMENU.NOMEM 

Not  enough  memory. 

Result:  MenuStrip     address,     might     not     be     complete 

(GTMENUJTRIMMED)  or  0.  MenuStrips  are  created 
without  locations.  Therefore,  LayoutMenusA()  or 
LayoutMenuItemsA()  must  be  called  before  they  are 

added. 
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| DrawBevelBox A  Draw  a  box | 

Coll:  DrawBevelBoxA(rport,  left,  top,  width,  height,  taglist) 

-120 (A6)      A0     DO    Dl   D2     D3      A3 


STRUCT  RastPort  *rport 

WORD   left, top, width, height 

STRUCT  Tagltem  *taglist 

Function:     Draws  a  box  in  a  RastPort. 


Parameters:  rport 

RastPort 

left 

Left  edge  of  box 

top 

Top  edge  of  box 

width 

Width  of  box 

height 

Height  of  box 

taglist 

Tagltem  field 

Tags:  GTBB_Recessed  (BOOL)  is  used  to  draw  a  new  box; 

otherwise  the  box  is  removed. 

GT_VisualInfo  (APTR)  must  be  given  with  the  result  of  a 
GetVisuallnfoAO  call. 

IFreeGadgets  Free  gadgets  | 

Call:  FreeGadgets(glist) 

-36 (A6)  A0 

STRUCT  Gadget   *glist 

Function:      Frees  all  memory  for  a  gadget  list  whose  components  were 
allocated  with  CreateGadgetA(). 

Parameters:  glist  One  or  more  linked  gadget  structures. 

I  FreeMenus  Free  menus  I 

Call:  FreeMenus  (menu) 

-54 (A6)         A0 

STRUCT  Menu   *menu 
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Function:      Free  all  memory  for  menus  created  with  CreateMenusA(). 

Parameters:  menu  Menu  or  Menultem  from  CreateMenusA(). 

IFreeVisuallnfo  Free  Visuallnfol 

Call:  FreeVisuallnf  o  ( vi ) 

-132 (A6)  AO 

APTR  vi 

Function:  Frees  memory  and  resources  allocated  with 
GetVisualInfoA().  This  function  may  only  be  called  after 
gadgets  are  used,  for  example,  after  a  window  is  closed.  It 
must  be  called  before  closing  or  unlocking  a  screen. 

Parameters:  vi  Result  from  GetVisualInfoA() 

|  Get Visuallnfo A  Get  information  on  the  screen  display  | 

Call:  vi  =  GetVisuallnfoA( screen,  taglist) 

DO    -126 (A6)        AO      Al 

APTR  vi 

STRUCT  Screen  * screen 

STRUCT  Tagltera  *taglist 

Function:  Gets  the  information  that  the  GadTools  library  needs  to 
create  the  best  possible  gadgets  or  menus.  After  a  window 
is  closed  for  the  last  time,  the  result  must  be  freed  with 
FreeVisuallnf o(). 

Parameters:  screen         Screen  where  the  window  is  to  be  opened. 

taglist         Tagltems  field 

Result:  Address  of  a  private  data  field. 

|GT  BeginRefresh  BeginRefresh  for  GadTools  windows] 

Call:  GT_BeginRefresh(win) 

-90 (A6)  AO 
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STRUCT  Window  *win 

Function:  Executes  the  BeginRefresh()  (known  from  Intuition)  for 
windows  with  GadTools  structures  (GadTools  works  with 
NOCAREREFRESH  windows). 

Parameters:  win  Window  that         receives  an 

IDCMP_REFRESHWINDOW  message. 

|GT  EndRefresh  End  refresh] 

Call:  GT_EndRefresh(win,    complete) 

-96  (A6)  AO        DO 

STRUCT  Window  *win 
BOOL       complete 

Function:  Ends  a  window  refresh  that  was  started  with 
GT_BeginRefresh(). 

Parameters:  win  Window  structure 

complete     Flag:  TRUE=refresh  completed 

|GT  FilterlMsg  Pass  Intuition  message  to  GadTools  | 

Call:  modimsg  =  GT_FilterlMsg(imsg) 

DO  -102 (A6)  Al 

STRUCT  IntuiMessage  *modimsg, *imsg 

Function:  Passes  an  Intuition  message  to  the  GadTools  library  to 
assure  proper  control  of  GadTools  gadgets. 

Parameters:  imsg  Normal  IntuiMessage  from  a  window  UserPort. 

Result:  0  if  GadTools  was  not  interested  in  the  message;  otherwise 

an  IntuiMessage  modified  with  information  from  GadTools. 
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|GT  GetlMsg  Get  and  process  an  IntuiMessage| 

Call:  imsg  =  GT_GetIMsg(intuiport) 

DO  -72 (A6)  AO 

STRUCT  IntuiMessage  *imsg 
STRUCT  MsgPort   *intuiport 

Functions,  Results: 

Similar  to  GT_FilterIMsg(),  except  that  the  message  is  first 
retrieved  from  the  given  port  with  GetMsg(). 

Parameters:  intuiport     UserPort  for  a  window. 

|GT  PostFilterlMsg  Restore  an  IntuiMessage  | 

Call:  imsg  =  GT_PostFilterIMsg(modimsg) 

DO  -108 (A6)  Al 

STRUCT  IntuiMessage  *imsg, *modimsg 

Function:  Messages  modified  by  GadTools  must  not  be  answered 
with  ReplyMsg().  This  function  returns  the  original 
message  and  frees  the  memory  used  by  the  modified 
message. 

Parameters:  modimsg     A  GadTools  message  from  GT_GetIMsg()  or 

GT_FilterIMsg(). 

Result:  The  original  IntuiMessage. 

|GT  Refresh  Window  Refresh  all  GadTools  gadgets  | 

Call:  GT_RefreshWindow(win,    req) 

-84 (A6)  AO        Al 

STRUCT  Window  *win 
STRUCT  Requester  *req 

Function:  Calling  intuition/RefreshGList()  after  intuition/AddGList() 
is  not  enough  to  properly  display  GadTools  gadgets.  This 
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function  must  also  be  called.  Afterwards,  it  is  no  longer 
needed. 

Parameters:  win  Window  with  GadTools  gadgets. 

req  Requester  address  (not  yet  supported:  0) 

|GT  ReplylMsg  Reply  to  a  GadTools  message  | 

Call:  GT_Reply  iMsg  ( imsg ) 

-78 (A6)  Al 

STRUCT  IntuiMessage   *imsg 

Function:      Replies  to  a  message  obtained  with  GT_GetIMsg(). 

Parameters:  imsg  A  modified  IntuiMessage  from  GT_GetIMsg(). 

|GT  SetGadgetAttrsA         Change  attributes  of  a  GadTools  gadget! 

Call:  GT_SetGadgetAttrsA(gad,    win,    req,    taglist) 

-42  (A6)  AO        Al        A2        A3 

STRUCT  Gadget   *gad 
STRUCT  Window  *win 
STRUCT  Requester  *req 
STRUCT  Tagltem  *taglist 

Function:      Changes  the  attributes  of  a  GadTools  gadget  according  to 
the  information  in  a  Tagltem  field. 

Parameters:  gad  GadTools  gadget 

win  Window  containing  the  gadget. 

req  Requester  for  the  gadget  (not  yet  supported: 

0). 

taglist         Tagltem  field 

Tags:  BUTTON-Gadget:  GA_Disabled. 

CHECKBOX-Gadget:      GTCB_Checked,  GA_Disabled. 
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CYCLE-Gadget:  GTCY_Active,  GTCY.Labels, 

GA_Disabled. 
INTEGER-Gadget:  GTIN_Number,  GA_Disabled. 

LISTVIEW-Gadget:         GTLV_Top,  GTLVLabels, 

GTLV_Selected. 
MX-Gadget:  GTMX_Active. 

NUMBER-Gadget:  GTNM_Number. 

PALETTE-Gadget:  GTPA_Color,  GA_Disabled. 

SCROLLER-Gadget:       GTSCTop,  GTSC_Total, 

GTSC_Visible,  GA_Disabled. 
SLroER-Gadget:  GTSL_Min,  GTSL_Max, 

GTSLLevel,  GA_Disabled. 
STRING-Gadget:  GTSTJString,  GA_Disabled. 

TEXT-Gadget:  GTTX_Text. 

|  LayoutMenuItemsA  Enter  positions  for  Mcnultems  | 

Call:  success  =  LayoutMenuItemsA (menuitem,  vi,  taglist) 

DO         -60  (A6)  A0         Al   A2 

BOOL    success 

STRUCT  Menuitem  *menuitem 

APTR   vi 

STRUCT  Tagltem  *taglist 

Function:     Enters  the  positions  of  Menultems  and  Subltems. 
Parameters:  menuitem    First  Menuitem 

vi  Result  of  GetVisualInfoA(). 

taglist         Description  of  the  items. 

Tags:  GTMN_TextAttr  (STRUCT  TextAttr  *)  defines  the  font  for 

Menultems  and  Subltems.  The  font  must  be  accessible  with 
graphics/OpenFontO . 

GTMN_Menu  (STRUCT  Menu  *)  gives  GadTools  the 
address  of  the  Menu  structure  of  the  given  items  (needed 
for  calculations). 
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Result: 


Error 


ILayoutMenusA 


Enter  position  in  MenuStrip| 


Call:  success  =  LayoutMenusA(menu,    vi,    taglist) 

DO  -66 (A6)  AO  Al      A2 

BOOL        success 
STRUCT  Menu   *menu 
APTR       vi 
STRUCT  Tagltem  *taglist 

Function:      Enters  positions  for  an  entire  MenuStrip. 
Parameters:  menu  MenuStrip  address  from  CreateMenusA(). 

vi  Result  from  GetVisualInfoA(). 

taglist         Tagltem  field 

Tags:  GTMN_TextAttr     (STRUCT     TextAttr      *)      see 

LayoutMenuItemsA(). 


Result: 


0 


Error 


GENERIC_KIND 

= 

0 

; standard  gadget 

BUTTON_KIND 

= 

1 

CHECKBOX_KIND 

= 

2 

INTEGER_KIND 

= 

3 

LISTVIEW_KIND 

= 

4 

MX_KIND 

= 

5 

NUMBER_KIND 

= 

6 

CYCLE_KIND 

= 

7 

PALETTE_KIND 

= 

8 

SCROLLER_KIND 

= 

9 

SLIDER_KIND 

= 

11 

STRING_KIND 

= 

12 

TEXT_KIND 

= 

13 

NUM_KINDS 

= 

14 

/number  of  new  gadg 

GADTOOLBIT 

= 

$8000  ;GadTools  gadget 

GADTOOLMASK 

= 

$7FFF  ;user  bits 
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Required  1DCMP  Flags: 


ARROWIDCMP 

BUTTONIDCMP 

CHECKBOXIDCMP 

INTEGERIDCMP 

LISTVIEWIDCMP 

MXIDCMP 

NUMBERIDCMP 

CYCLEIDCMP 

PALETTEIDCMP 

SCROLLERIDCMP 

SLIDERIDCMP 

STRINGIDCMP 

TEXTIDCMP 


GADGETUP ! GADGETDOWN ! INTUITICKS ! MOUSEBUTTONS 

GADGETUP 

GADGETUP 

GADGETUP 

GADGETUP  !  GADGETDOWN !  MOUSEMOVE  !  ARROWIDCMP 

GADGETDOWN 

0 

GADGETUP 

GADGETUP 

GADGETUP ! GADGETDOWN ! MOUSEMOVE  ; wi  t hout  arrows ! 

GADGETUP ! GADGETDOWN ! MOUSEMOVE 

GADGETUP 


Spacing: 


INTERWIDTH 

=  8 

INTERHEIGHT 

=  4 

Dec  Hex 

STRUCTURE  NewGadget.O 

0   $0 

WORD 

gng_Lef tEdge 

;gadget  position 

2   $2 

WORD 

gng_TopEdge 

4   $4 

WORD 

gng_Width 

,-  gadget  size 

6   $6 

WORD 

gng_Height 

8   $8 

APTR 

gng_GadgetText 

;  text 

12   $C 

APTR 

gng_TextAttr 

;  font  for  the  text 

16  $10 

UWORD 

gng_GadgetID 

;ID 

18  $12 

ULONG 

gng_Flags 

; Flags 

22  $16 

APTR 

gng_VisualInfo 

;see  GetVisualInfo( ) 

26  $1A  APTR 

gng_UserData 

,-user  data 

30  $1E 

LABEL 

gng_SIZEOF 

PLACETEXT_LEFT   =  $0001  ;next  to  slider,  left 

PLACETEXTJRIGHT  =  $0002  ; right  next  to  slider,  right 

PLACETEXT_ABOVE  =  $0004  ; above  slider 

PLACETEXT_BELOW  =  $0008  ,-below  slider 

PLACETEXT_IN     =  $0010  ; in  the  gadget 

NG_HIGHLABEL    =  $0020  ; highlight 


Dec  Hex  STRUCTURE  NewMenu , 0 

0  $0  UBYTE  gnm_Type 

1  $1  UBYTE  gnm_Pad 

2  $2  APTR   gnm_Label 

6   $6  APTR   gnm_CommKey 
10   $A  UWORD  gnm_Flags 


;  type 

;  text 

; character 

; structure 


12   $C  LONG   gnm_Mutual Exclude   ; exclude 
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16  $10  APTR   gnm_UserData 
20  $14  LABEL   gnm_SIZEOF 


;user  data 


UserData  always  comes  after  the  normal  structure,  for  example,  as  with 
mu_SIZEOF(Menu). 


NMJTITLE  =  1  ;Menu 
NM_ITEM  =  2  ;MenuItem 
MM_SUB    =  3  ;SubItem 
NM_END   =  0  ;end  of  field 

MENU  IMAGE  =  128 


; Image  flag 


IM_ITEM    =  NM_ITEM!MENU_IMAGE  ; item  with  image 
IM_SUB     =  NM_SUB!MENU_IMAGE   ;SubItem  with  image 


NM_BARLABEL 


-1  ; dividing  line 


NM_MENUDISABLED  =  MENUENABLED 
NM_ITEMDISABLED  =  ITEMENABLED 

NM_FLAGMASK  =  - (COMMSEQ! ITEMTEXTIHIGHFLAGS) 


GT_TagBase 

GTVI_NewWindow 

GTVI_NWTags 

GT_PrivateO 

GTCB_Checked 

GTLV_Top 

GTLV_Labels 

GTLV_ReadOnly 

GTLV_Scrol lWidth 

GTMX_Labels 

GTMX_Active 

GTTX_Text 

GTTX_CopyText 

GTNM^Number 

GTCY_Labels 

GTCY_Active 

GTPA_Depth 

GTPA_Color 

GTPAColorOffset 


=  TAG_USER+$80000 
=  GT_TagBase+$01 
=  GT_TagBase+$02 
=  GT_TagBase+$03 
=  GT_TagBase+$04 
=  GT_TagBase+$05 
=  GT_TagBase+$06 
=  GT_TagBase+$07 

GT_TagBase+$08 
=  GT_TagBase+$09 
=  GT_TagBase+$0A 
=  GT_TagBase+$0B 
=  GT_TagBase+$0C 
=  GT_TagBase+$0D 
=  GT_TagBase+$0E 
=  GT_TagBase+$0F 
=  GT_TagBase+$10  • 
=  GT_TagBase+$ll 

GT_TagBase+$12 


GTPA_IndicatorWidth  =GT_TagBase+$13 
GTPA_IndicatorHeight=GT_TagBase+$14 
GTSC_Top        =  GT_TagBase+$15 
GTSC_Total      =  GT_TagBase+$16 
GTSC_Visible    =  GT_TagBase+$17 
GTSC_Overlap    =  GT_TagBase+$18 


first  Tag 

NewWindow  for  Visual Info 

NewWindow  Tags 

private 

checkbox  status 

top  of  ListView 

ListView  contents 

ListView  type 

ListView  scroller  width 

MX  contents 

MX  prefix 

text 

copy  text 

number  value 

cycle  contents 

cycle  prefix 

palette  bit  planes 

palette  prefix 

palette  start 

palette  indicator  width 

palette  indicator  height 

top  of  scroller 

total  contents  of  scroller 

scroller  contents 

not  used 
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GTSL_Min 
GTSL^Max 

GTSL_Level  = 
GTSL_MaxLevelLen= 
GTSL_LevelFormat= 
GTSL_LevelPlace  = 
GTSL_DispFunc  = 
GTST_String  = 
GTST_MaxChars  = 
GTIN_Number  = 
GTIN_MaxChars  = 
GTMN_TextAttr  = 
GTMN_FrontPen  = 
GTBB_Recessed  = 
GT_VisualInfo  = 
GTLV_ShowSelected 
GTLV_Selected  = 
GT_ReservedO  = 
GT_Reservedl  = 
GTTX_Border  = 
GTNM_Border  = 
GTSC_Arrows  = 
GTMN_Menu  = 
GTMX_Spacing    = 


GT_TagBase+  $2  6 
GT_TagBase+$27 
GT_TagBase+$28 
GT_TagBase+$29 
GT_TagBase+  $2A 
GT_TagBase+$2B 
GT_TagBase+$2C 
GT_TagBase+  $2D 
GT_TagBase+$2E 
GT_TagBase+$2F 
GT_TagBase+$3  0 
GT_TagBase+$31 
GT_TagBase+$32 
GT_TagBase+$33 
GT_TagBase+  $3  4 
=GT_TagBase+$35 
GT_TagBase+$36 
GT_TagBase+$37 
GT_TagBase+$38 
GT_TagBase+$39 
GT_TagBase+$3A 
GT_TagBase+$3B 
GT_TagBase+$3C 
GT_TagBase+$3D 

Example 


slider  minimum 
slider  maximum 
slider  position 
slider  text  length 
slider  format  string 
slider  text  position 
slider  function 
string  contents 
string  text  length 
integer  value 
integer  text  length 
Menultem  font 
Menultem  text  color 
BevelBox  recessed 
Visuallnfo 
ListView  display 
ListView  prefix 
reserved 
reserved 
text  border 
number  border 
scroller  arrows 
menu  address 
MX  spacing 


Create  gadgets.  In  some  cases,  using  GadTools  can  be  more  difficult  than 
creating  the  gadgets  yourself.  But  your  efforts  will  be  rewarded  with 
gadgets  that  have  the  new,  professional-looking  standard  appearance. 
Also,  you  won't  have  to  program  the  query  routines  for  the  new  gadget 
types  yourself. 


bsr 

_CreateGadgets 

beq 

_NoGadgets 

movea . 1 

_Window,aO 

movea . 1 

_GadgetListe(pc) ,al 

moveq 

#-l,dO 

moveq 

#-l,dl 

lea 

$0.w,a2 

movea . 1 

_IntuiBase,a6 

jsr 

_LVOAddGList(a6) 

movea. 1  _GadgetListe(pc) ,a0 
movea . 1  _Window, al 
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moveq    #-l,dO 

jsr     _LVORefreshGList (a6) 

movea . 1  _Window , aO 

movea.l  a2,al 

movea. 1  _GadToolsBase, a6 

jsr     _LVOGT_RefreshWindow(a6) 


_CreateGadgets 

movea.l  _GadToolsBase, a6 

movea.l  _MyScreen,aO 

lea  _DummyTags , al 

jsr  _LVOGetVisualInfoA(a6) 

move . 1  dO,_VisualInfo 

beq  _Zerrorl 

lea  _Gadgetliste(pc) ,a0 

jsr  _LVOCreateContext (a6) 

tst.l  dO 

beq  _Zerror2 


movea 

1  dO,aO 

moveq 

#CYCLE_KIND,dO 

lea 

_NewGadget (pc) , al 

lea 

_TagList (pc) ,a2 

jsr 

_LVOCreateGadgetA ( a6 ) 

tst.l 

dO 

beq 

_Zerror3 

rts 

_Zerror3 

movea.l  _GadgetListe (pc) , aO 
jsr     _LVOFreeGadgets(a6) 

_Zerror2 

movea.l  _VisualInf o, aO 
jsr     _FreeVisualInfo(a6) 

_Zerrorl 
moveq   #0,d0 
rts 

_DummyTags 
del   TAG_DONE 


250 


3.1   The  Libraries  and  their  Functions 


_Gadgetliste 
del   0 

_NewGadget 

dew   10,10,80,12 

del    0,_Topaz8 

dew  1 

del    0 
_VisualInfo 

de  1   0,0 

_Topaz8 
dc . 1  _TopazName 
dew  8 
dc . b   0,0 

_TagList 
del   GTCY_Labels,_Strings 
del   TAG_DONE 

_Strings 
del   _TextO,_Textl,_Text2,_Text3,  0 

_TopazName 
deb    •  topaz  .  font ',  0 

_Text0 
deb    'DFO:  '  ,0 

_Textl 
deb    'DF1:  '  ,0 

_Text2 

de  b    '  DF2  :  '  ,  0 

_Text3 
deb    'DF3:  '  ,0 

3.1.8  The  Graphics  Library 


Programmers  often  refer  to  "graphics.library"  (its  proper  name  for  the 
OpenDevice()  function)  as  the  Gfx  library.  Gfx  is  responsible  for  all 
display  and  graphics  operations.  This  library  is  used  to  program  the  blitter 
and  the  copper  which  control  the  video  hardware.  These  routines  are 
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used  for  such  operations  as  drawing,  text  output,  and  displaying  movable 
objects.  The  base  address  must  always  be  passed  in  A6. 


Functions  of  the  Gfx  Library 

1.  The  Video  Hardware 

CBump 

CloseMonitor 

CMove 

CWait 

FindDisplaylnfo 

FreeCopList 

FreeCprList 

FreeVPortCopLists 

GetDisplaylnfoData 

GetVPModelD 

LoadRGB4 

LoadView 

MakeVPort 

ModeNotAvailable 

MrgCop 

NextDisplaylnfo 

OpenMonitor 

ScrollVPort 

SetRGB4 

VBeamPos 

VideoControl 

WaitBOVP 

WaitTOF 

2.  General  Blitter  Control 

BitMapScale 

BltBitMap 

BltBitMapRastPort 

BltClear 

BltMaskBitMapRast 

Port 

BltPattern 

BltTemplate 

QipBlit 


CopySBitMap 

DisOwnBlitter 

OwnBlitter 

QBlit 

QBSBlit 

ScalerDiv 

ScrollRaster 

SyncSBitMap 

WaitBlit 

3.  Refresh  Functions 

AndRectRegion 

AndRegionRegion 

ClearRectRegion 

ClearRegion 

DisposeRegion 

NewRegion 

OrRectRegion 

OrRegionRegion 

XorRectRegion 

XorRegionRegion 

4.  Data  Structures 

AllocRaster 

AttemptLockLayerRom 

FreeColorMap 

FreeRaster 

GetColorMap 

GetRGB4 

InitBitMap 

InitRastPort 

InitTmpRas 

InitView 

InitVPort 

LockLayerRom 
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SetRGB4CM 
UnlockLayerRom 

5.  Draw  Functions 

AreaDraw 

AreaEllipse 

AreaEnd 

AreaMove 

Draw 

DrawEllipse 

EraseRect 

Flood 

InitArea 

Move 

PolyDraw 

ReadPixel 

ReadPixelArray8 

ReadPixelLine8 

RectFill 

SetAPen 

SetBPen 

SetDrMd 

SetRast 

WritePixel 

WritePixelArray8 

WritePixelLine8 

6.  Text  Output 

AddFont 

AskFont 

AskSoftStyle 

ClearEOL 

ClearScreen 


CloseFont 

ExtendFont 

FontExtent 

OpenFont 

RemFont 

SetFont 

SetSoftStyle 

StripFont 

Text 

TextExtent 

TextFit 

TextLength 

WeighTAMatch 

7.  Movable  Objects 

AddAnimOb 

AddBob 

AddVSprite 

Animate 

ChangeSprite 

DoCollision 

DrawGList 

FreeGBuffers 

FreeSprite 

GetGBuffers 

GetSprite 

InitGels 

InitGMasks 

InitMasks 

MoveSprite 

RemlBob 

RemVSprite 

SetCollision 

SortGList 
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Description  of  Functions 

1.  The  Video  Hardware 

[CBump  UCopList  pointer  to  the  next  instruction  | 

Call:  CBump  (  c  ) 

-366 (A6)    al 

STRUCT  UCopList  *C 

Function:     Sets  the  command  pointer  of  a  user  Copper  list  to  the  next 
command. 

Parameters:  c  Address  of  a  UCopList  structure. 

[CloseMonitor  Close  Monitor  Spec  | 

Call:  error  =  CloseMonitor  (  monitor_spec   ) 

dO  -720 (A6)  aO 

LONG  error 

STRUCT  MonitorSpec  *monitor_spec 

Function:     Closes  the  given  MonitorSpec. 

Parameters:  monitor_spec 

MonitorSpec  address  from  OpenMonitorQ. 

Result:  0  MonitorSpec  closed 

[CMove  Write  a  Copper  move  instruction  to  the  UCopList \ 

Call:  CMove  (  c  ,   a  ,   v  ) 

-372(A6)al  dO  dl 

STRUCT  UCopList  *C 
SHORT   a,v 

Function:     Writes  a  Copper  move  command  to  a  user  Copper  list 
without  changing  the  edit  pointer. 
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Parameters:  c  UCopList  structure 

a  Hardware  register  offset  from  $DFF000. 

v  Word  to  which  the  register  will  be  written. 

I C Wait  Enter  Copper  wait  in  UCopList  | 

Call:  cwait(  c  ,  v  ,   h  ) 

-378 (A6)    al  dO  dl 

STRUCT  UCopList  *C 
SHORT   v,h 

Function:      Writes  a  Copper  wait  command  to  the  user  Copper  list 
without  changing  the  edit  position. 

Parameters:  c  UCopList  structure 

v  Vertical  wait  position  (end  =  10000). 

h  Horizontal  wait  position  (end  =  255). 

| FindDisplaylnfo  Get  info  on  the  display  model 

Call:  handle  =  FindDisplaylnfo  (   ID   ) 

dO  -726 (A6)  dO 

ULONG      ID 
LONG       handle 

Function:      Finds  the  information  structure  for  a  given  display  mode. 

Parameters:  ID  32    bit    display    mode    (monitor    specific 

ViewMode). 

Result:  Handle  to  DisplaylnfoRecord  or  0. 

|  FreeCopList  Free  Copper  list  buffer] 

Call:  FreeCopList  (coplist) 

-546 (A6)  aO 
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struct  CopList  *coplist 

Function:      Frees  the  memory  used  by  a  Copper  list. 

Parameters:  coplist         CopList  structure 

IFreeCprList  Free  a  hardware  Copper  listj 

Call:  FreeCprList  (cprlist) 

-564 (A6)  aO 

STRUCT  cprlist  *cprlist 

Function:      Frees  the  memory  of  a  hardware  Copper  list. 

Parameters:  cprlist         cprlist  structure 

|  Free VPortCopLists  Free  ViewPort  Copper  lists  | 

Call:  FreeVPortCopLists  (vp) 

-540 (A6)  aO 

STRUCT  ViewPort   *vp 

Function:     Frees  the  memory  for  all  Copper  lists  of  a  ViewPort. 

Parameters:  vp  ViewPort 

1  GetDisplaylnfoData  Get  data  associated  with  a  display  mode  | 

Call:  result  =  GetDisplaylnfoData  (handle,  buf,  size,  tagID,  ID) 

dO       -756 (A6)  aO      al   dO    dl     d2 

LONG  handle 

APTR  buf 

ULONG  size, tagID, ID, result 

Function:      Fills  a  buffer  with  data  associated  with  a  display  mode. 
Parameters:  handle        Displaylnfo  handle  of  the  display  mode. 
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buf 

Buffer  to  be  filled 

size 

Buffer  size 

tagID 

Desired  data  type: 

DTAG_DISP 

DTAG_DMS 

DTAG_MNTR 

DTAG_NAME 

Displaylnfo  structure 
Dimensionlnfo  structure 
Monitorlnfo  structure 
Display  mode  name 

ID  32  bit  display  mode  (if  handle=0). 

Result:  Number  of  bytes  in  buffer,  0  (unknown  mode  or  error). 

IGetVPModelD  Get  a  monitor  specific  display  model 

Call:  modelD  =  GetVPModelD  (  vp   ) 

dO  -792 (A6)  aO 

STRUCT  Viewport   *vp 
ULONG     modelD 

Function:  Retrieves  the  monitor  specific  32  bit  display  mode  of  a 
ViewPort. 

Parameters:  vp  ViewPort  structure 

Result:  ModelD  or  INVALIDJD 

|LoadRGB4  Set  color  table | 

Call:  LoadRGB4  (  vp,    colors    ,    count    ) 

-192 (A6)      aO     al  d0:16 

STRUCT  ViewPort   *vp 
APTR       colors 
SHORT     count 

Function:  Loads  the  3x4  bit  RGB  color  values  from  a  table  to  the 
ColorMap  of  the  ViewPort,  recalculates  the  Copper  lists, 
and  controls  the  video  hardware. 
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Parameters:  vp  ViewPort  whose  colors  are  to  be  changed. 

colors  Word  array  with  color  values  ($ORGB). 

count  Number  of  colors  (including  0). 
|  Load  View  Activate  a  Copper  list  | 

Call:  Loadview(  View  ) 

-222 (A6)      Al 

STRUCT  View  *View 

Function:  Activates  the  Copper  list  of  a  view  (available  after 
MakeView(),  MrgCopO)  until  the  next  call.  Many 
programs,  handlers  (Intuition,  Workbench...)  and  operating 
system  routines  call  this  function,  so  a  good  knowledge  of 
the  system  is  required  for  error-free  programming. 

Parameters:  View  View  structure  with  Copper  lists  or  0  (screen 

off  but  DMA  still  running,  as,  for  example,  with 
the  sprite  DMA). 

|  Make  VPort  Assemble  the  Copper  lists  of  a  ViewPort  | 

Call:  MakeVPort  (  view,   viewport   ) 

-216 (A6)        aO  al 

STRUCT  View  *view 

STRUCT  ViewPort   *viewport 

Function:     Derives  the  Copper  lists  of  a  ViewPort. 

Parameters:  view  View  structure  of  the  ViewPorts. 

viewport     ViewPort  structure  with  Raslnfo. 

| ModeNot Available  Checks  on  availability  of  a  display  model 

Call:  error  =  ModeNotAvailable  (  modelD  ) 

dO  -798  (A6)  dO 
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ULONG  modelD, error 

Function:     Checks  for  the  availability  of  a  monitor  specific  32  bit 
display  mode. 

Parameters:  modelD       32  bit  display  mode 

Result:  Error  code  that  describes  why  the  mode  is  not  available,  or 

0  if  the  system  does  not  have  a  reason  why  this  mode  can't 

be  used. 

I  MrgCop  Merge  Copper  lists  \ 

Call:  MrgCop  (  view  ) 

-210 (A6)    Al 

STRUCT  View  *View 

Function:     Merges  all  partial  Copper  lists  into  a  proper  Copper  list. 

Parameters:  View  View  structure  with  partial  Copper  lists. 

|  NextDisplay Info  Read  through  list  of  display  modes  | 

Call:  next_lD  =  NextDisplay Inf o  (   last_lD  ) 

dO  -732 (A6)  dO 

ULONG  last_ID,next_ID 

Function:      Gets  the  next  available  monitor  specific  display  mode. 

Parameters:  lastJD       Result  of  the  last  call  or  INVALIDJD  for  the 

start  of  the  list. 

Result:  32  bit  display  mode  or  INVALID_ID  (no  more  modes). 

IQpenMonitor  Open  Monitor  Spec! 

Call:  mspc  =  OpenMonitor(  monitor_name  ,  display_id) 

dO     -714 (A6)     al  dO 


APTR   monitor_name 


259 


3.  Programming  with  AmigaOS  2.x 


ULONG  display_id 
STRUCT  MonitorSpec  *mspc 

Function:  Opens  a  MonitorSpec  which  is  given  the  monitor  name  or 
the  32  bit  ID.  If  both  parameters  are  0,  then  the  default 
monitor  is  returned. 

Parameters:  monitor_name 

Monitor  name  or  0. 

displayed  32  bit  display  mode  or  0. 

Result:  MonitorSpec  structure  or  0. 

|  Scroll VPort  Scroti  ViewPort  contents] 

Call:  ScrollVPort(  vp   ) 

-588 (A6)  aO 

STRUCT  Viewport  *vp 

Function:  Called  after  changing  the  Raslnfo  offsets  and  BitMap 
pointer  to  recalculate  the  Copper  lists.  Warning:  high  level 
languages  are  too  slow. 

Parameters:  vp  Visible  ViewPort 

|SetRGB4  Change  colors  I 

Call:  SetRGB4  (  vp,   n,   r,       g,       b) 

-288 (A6)    aO      dO   dl:4   d2 : 4   d3:4 

STRUCT  ViewPort  *vp 
SHORT  n 
UBYTE  r,g,b 

Function:  Sets  the  color  intensity  of  a  color  register,  recalculates  the 
Copper  list,  which  controls  the  hardware. 

Parameters:  vp  ViewPort 

n  Color  number  (0...3 1 ) 
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g 

b 


IVBeamPos" 


Call:  pos  =  VBeamPos  ( ) 

dO  -384 (A6) 


3.1  The  Libraries  and  their  Functions 

Red  intensity  (0...15) 
Green  intensity  (0...15) 
Blue  intensity  (0...15) 

Get  the  vertical  beam  position] 


LONG   pos 

Function:      Gets  the  position  of  the  monitor's  vertical  beam. 

Result:  Vertical  beam  position  (0...511).  The  uncertainty  is 

extremely  high  and  is  only  acceptable  for  a  task  with  the 
highest  priority. 


IVideoControl 


Change  the  color  operations  of  a  ViewPort] 


Call:  error  =  VideoControl  (   cm   ,    tags   ) 

dO  -708 (A6)  aO        al 

LONG  error 

STRUCT  ColorMap  *cm 

STRUCT  Tagltem  *tags 

Function:     Change  the  operation  of  a  ViewPort's  ColorMap  according 
to  the  commands  in  a  Tagltem  field. 


Parameters:  cm 

tags 
Tags: 


ColorMap,  result  of  GetColorMap(). 
Tagltem  field 


VTAG_ATTACH_CM_..  get  the  ViewPort  of  the  ColorMap 
(..GET),  set  (..SET). 

VTAG_VIEWPORTEXTRA_..  get  vp_extra  (..GET),  set 
(..SET). 
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VTAG_NORMAL_DISP_..   get   DisplaylnfoHandle   in 
normal  mode  (..GET),  set  (..SET). 

VTAG_COERCE_DISP_..  same  for  coerced  mode  (..GET, 
..SET). 

VTAG_BORDERBLANK_..  Genlock:  set  border  blanking 
(..SET),  clear  (..CLR),  get  (..GET). 

VTAG_BORDERNOTRANS_..  set  no-transparency  in  the 
border  region  (..SET),  clear  (..CLR),  get  (..GET). 

VTAG_CHROMAKEY_..  set  Chroma  mode  (..SET),  clear 
(..CLR),  get  (..GET). 

VTAG_BITPLANEKEY_..  set  BitPlane  mode  (..SET),  clear 
(..CLR),  get  (..GET). 

VTAG_CHROMA_PEN_..   set  Chroma  color  number 
(..SET),  clear  (..CLR),  get  (..GET). 

VTAG_CHROMA_PLANE_..  set  BitPlane  number  (..SET), 
get  (..GET). 

VTAG_NEXTBUF_CM  next  command  list. 

VTAG_END_CM  last  command. 

Result:  0  Okay,     followed     by     adding     the     next 

MakeVPort(). 

|  WaitBO VP  Wait  until  a  ViewPort  is  scanned  | 

Call:  waitBOVP(  vp  ) 

-402 (A6)      aO 

STRUCT  ViewPort  *vp 

Function:      Waits  until  the  monitor  beam  has  displayed  the  last  visible 
line  of  the  given  ViewPort. 
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Parameters:  vp 


IWaitTGF 


ViewPort 


Wait  for  vertical  scan  interrupts! 


COPPER_MOVE 

COPPER_WAIT 

CPRNXTBUF 

CPR_NT_LOF 

CPR_NT_SHT 

CPR_NT_SYS 


Call:  waitTOF  ( ) 

-270 (A6) 

Function:  Waits  for  the  monitor's  next  vertical  scan  and  for  all  VertB 
interrupt  routines  to  be  processed  (turning  off  tasks,  signal 
through  VertB  handler). 

Pseudo  Opcodes  for  lists: 

=      0  ; Pseudo  Opcode  for  MOVE  #...,... 
=     1  ; Pseudo  Opcode  for  WAIT  ....... 

=     2  ;end  of  buffer 

=  $8000  ; command  for  Shortframes 

=  $4000  .-command  for  Longframes  (2.  Interlace) 

=  $2000  ;User  command 


Dec  Hex  STRUCTURE  CopIns.O 
0   $0  WORD    ci_OpCode 
$2  STRUCT  ci_nxtlist,0 
$2  STRUCT  ci_VWaitPos,0 


; Copper  Pseudo  Opcode 

;0  =  move,  1  =  wait 

; address  of  the  next  buffer 

;or  wait  position 


$2  STRUCT  ci_DestAddr,2  ;or  destination  address 
$4  STRUCT  ci_HWaitPos,0  ;2.  partial  wait  position 
$4  STRUCT  ci_DestData, 2  ;or  value 
$6  LABEL   ci_SIZEOF 


Dec  Hex  STRUCTURE  cprlist.O 
0   $0  APTR  crl_Next 
4   $4  APTR  crl_start 
8   $8  WORD  crl_MaxCount 
10   $A  LABEL  crl_SIZEOF 


.-management  of  true  Copper  lists 
; address 
,-  start 
;  length 


Dec  Hex  STRUCTURE  CopList,0 

0   $0  APTR  cl_Next 

4   $4  APTR  cl CopList 

8   $8  APTR  cl ViewPort 

12   $C  APTR  cl_CopIns 

16  $10  APTR  cl_CopPtr 

20  $14  APTR  cl_CopLStart 

24  $18  APTR  cl_CopSStart 

28  $1C  WORD  cl_Count 

30  $1E  WORD  cl_MaxCount 

32  $20  WORD  cl_DyOffset 


management  of  temporary  lists 

next  structure 

private 

private 

start  of  block 

command  address 

LongFrame  address  from  MrgCopO 

ShortFrame  address  fromMrgCopO 

counter 

block  length  in  Pseudo  Opcodes 

vertical  start  position 
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MODE_640    = 

$8000 

PLNCNTMSK   = 

7 

PLNCNTSHFT  = 

12 

PF2PRI 

$40 

COLORON 

$200 

DBLPF 

$400 

HOLDNMODIFY= 

$800 

INTERLACE   = 

4 

34  $22  LABEL  cl_SIZEOF 

Dec  Hex  STRUCTURE  UCopList.O  ;User  Copper  list 

0   $0  APTR   ucl_Next  ;next  list 

4   $4  APTR   ucl_FirstCopList  /first  node 

8   $8  APTR   ucl_CopList  /current  node 
12   $C  LABEL   ucl_SIZEOF 

;HiRes 

;bplcon0  bit  plane  mask 
;bplcon0  bit  plane  bit 
;Playfield  2  priority 
/suppress  Color  Burst 
;DualPlay field  mode 
;Hold-And-Modify  mode 
; Interlace  mode 

PFA_FINE_SCROLL       =   15  ,-Softscrolling  planes  0,2,4 
PFB_FINE_SCROLL_SHIFT  =    4  ;bit  position  for  planes  1,3,5 
PF_FINE_SCROLL_MASK   =   15  ;Softscrolling  planes  1,3,5 

DIW_HORIZ_POS  =  $7F  /horizontal  mask 

DIW_VRTCL_POS  =  $1FF  ,-vertical  mask 

DIW_VRTCL_POS_SHIFT  =     7  ;bit  position 

DFTCH_MASK  =   $FF  ;data  fetching  mask 

VPOSRLOF  =$8000  ;LongFrame  Flag  vpos 

DTAG_DISP  =  $80000000  ,-Display  Tags 
DTAG_DIMS  =  $80001000 
DTAG^MNTR  =  $80002000 
DTAG_NAME  =  $80003000 

Dec  Hex  STRUCTURE  QueryHeader , 0 

0   $0  ULONG  qh_StructID   ,-Display  Tag  ID 

4   $4  ULONG  qh_DisplayID  ;32  bit  mode 

8   $8  ULONG  qh_SkipID     ;TAG_SKIP 
12   $C  ULONG  qh_Length     ; length  in  8  byte  segments 
16  $10  LABEL   qh_SIZE0F 

Dec  Hex  STRUCTURE  Display Info,qh_SIZEOF 

16  $10  UWORD  dis_NotAvailable  ;Flag:  0=available 

18  $12  ULONG  dis_PropertyFlags  ; characteristics 

22  $16  STRUCT  dis_Resolution, tpt_SIZEOF  ;pixel  resolution  X/Y 

26  $1A  UWORD  dis_PixelSpeed  ; nanoseconds  per  pixel 

28  $1C  UWORD  dis_NumStdSprites  /number  of  sprites 

30  $1E  UWORD  dis_PaletteRange  ,-available  colors 
32  $20  STRUCT  dis_SpriteResolution, tpt_SIZEOF  ; sprite  resolution 
36  $24  STRUCT  dis_pad, 4 
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40  $28  STRUCT  dis_reserved, 8 
48  $30  LABEL   dis_SIZEOF 

DI_AVAIL_NOCHIPS  =  1 

DI_AVAIL_NOMONITOR  =  2 
DI_AVAIL_NOTWITHGENLOCK  =  4 

DIPF_IS_LACE  =  $00000001 

DIPF_IS_DUALPF  =  $00000002 

DIPF_IS_PF2PRI  =  $00000004 

DIPF_IS_HAM  =  $00000008 

DIPF_IS_ECS  =  $00000010 

DIPF_IS_PAL  =  $00000020 

DIPF_IS_SPRITES  =  $00000040 

DIPF_IS_GENLOCK  =  $00000080 

DIPF_IS_WB  =  $00000100 

DIPF_IS_DRAGGABLE  =  $00000200 

DIPF_IS_PANELLED  =  $00000400 

DIPF_IS_BEAMSYNC  =  $00000800 
DIPF_IS_EXTRAHALFBRITE   =  $00001000 

Dec  Hex  STRUCTURE  DimensionInfo,qh_SIZEOF 

16  $10  UWORD  dim_JfaxDepth  .-number  of  bit  planes 

18  $12  UWORD  dim_MinRasterWidth  .-minimum  width 

20  $14  UWORD  dim_MinRasterHeight  .-minimum  height 

22  $16  UWORD  dim_MaxRasterWidth  .-maximum  width 

24  $18  UWORD  dim_MaxRasterHeight  .-maximum  height 

26  $1A  STRUCT  dim_Nominal,  ra_SIZEOF  .-standard  dimensions 

34  $22  STRUCT  dim_MaxOScan ,  ra_SIZEOF  .-maximum  Overscan 

42  $2A  STRUCT  dim_VideoOScan,ra_SIZEOF  ,-video  Overscan 

50  $32  STRUCT  dim_TxtOScan ,  ra_SIZEOF  ,-text  Overscan  Prefs 

58  $3A  STRUCT  dim_StdOScan, ra_SIZEOF  ; standard  Overscan  Prefs 
66  $42  STRUCT  dim_pad, 14 
80  $50  STRUCT  dim_reserved, 8 
88  $58  LABEL  dim_SIZEOF 

Dec  Hex  STRUCTURE  Monitor Inf o, qh_SIZEOF 

16  $10  APTR   mtr_Mspc  ,-MonitorSpec 

20  $14  STRUCT  mtr_ViewPosition,tpt_SIZEOF  ; Prefs 

24  $18  STRUCT  mtr_ViewResolution,  tpt_SIZEOF  .-resolution 

28  $1C  STRUCT  mtr_ViewPositionRange, ra_SIZEOF  .-range 

36  $24  UWORD  mtr_TotalRows  ,-number  of  rows 

38  $26  UWORD  mtr_TotalColorClocks  ,-width  in  l/280ns 

40  $28  UWORD  mtr_MinRow  .-minimum  height 

42  $2A  WORD   mtr_Compatibility  ; compatibility 

44  $2C  STRUCT  mtr_pad,36 

80  $50  STRUCT  mtr_reserved, 8 

88  $58  LABEL  mtr_SIZEOF 
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MCOMPAT_MIXED  = 
MCOMPAT_SELF 

MCOMPAT_NOBODY  = 

DISPLAYNAMELEN  = 


0  ;mixed  display  allowed 

1  ;with  this  monitor  type  only 
-1  ;only  on  Viewport  allowed 

32  ; length  of  display  name 


Dec  Hex  STRUCTURE  NameInfo,qh_SIZEOF 
16  $10  STRUCT  nif_Name, DISPLAYNAMELEN  ;name 
48  $30  STRUCT  nif_reserved, 8 
56  $38  LABEL  nif_SIZEOF 


INVALID_ID 
MONITOR_ID_MASK 
DEFAULT_MONITOR_ID 
NTSC_MONITOR_ID 
PAL_MONITOR  ID 


-1 
$FFFF1000 
$00000000 
$00011000 
$00021000 


LORES_KEY  =  $00000000 

HIRES_KEY  =  $00008000 

SUPER_KEY  =  $00008020 

HAM_KEY  =  $00000800 

LORESLACE_KEY  =  $00000004 

HIRESLACE_KEY  =  $00008004 

SUPERLACE_KEY  =  $00008024 

HAMLACE_KEY  =  $00000804 

LORESDPF_KEY  =  $00000400 

HIRESDPF_KEY  =  $00008400 

SUPERDPF_KEY  =  $00008420 

LORESLACEDPF_KEY  =  $00000404 

HIRESLACEDPF_KEY  =  $00008404 

SUPERLACEDPF_KEY  =  $00008424 

LORESDPF2_KEY  =  $00000440 

HIRESDPF2_KEY  =  $00008440 

SUPERDPF2_KEY  =  $00008460 

LORESLACEDPF2_KEY  =  $00000444 

HIRESLACEDPF2_KEY  =  $00008444 

SUPERLACEDPF2_KEY  =  $00008464 

EXTRAHALFBRITE_KEY  =  $00000080 
EXTRAHALFBRITELACE_KEY   =  $00000084 


LoRes 

HiRes 

SuperHiRes 

HoldAndModify 

Interlace 

HiRes -Interlace 

SuperHiRes- Interlace 

HAM-Interlace 

DualPlayfield 

HiRes-DblPf 

SuperHiRes-DblPf 

Inter lace-DblPf 

HiRes -Inter lace-DblPf 

SuperHiRes- ILace-DblPf 

DualPlayfield2 

HiRes-DblPf2 

SuperHiRes-DblPf2 

Inter lace-DblPf2 

HiRes- Inter lace-DblPf 2 

SuperHRes- ILace-DblPf 2 

ExtraHalfbrite 

ExtraHalfbrite-ILace 


VGA_MONITOR_ID  =  $00031000 

VGAEXTRALORES_KEY  =  $00031004 

VGALORES_KEY  =  $00039004 

VGAPRODUCT_KEY  =  $00039024 

VGAHAM_KEY  =  $00031804 
VGAEXTRALORESLACE_KEY    =  $00031005 

VGALORESLACE_KEY  =  $00039005 

VGAPRODUCTLACE_KEY  =  $00039025 

VGAHAMLACE_KEY  =  $00031805 


;VGA  monitor 

;ExtraLoRes 

; LoRes 

/Productivity 

;HAM 

;ExtraLoRes-ILace 

; Interlace 

; Productivity-ILace 

; HAM-Interlace 
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VGAEXTRALORESDPF_KEY  =  $00031404 
VGALORESDPF_KEY  =  $00039404 

VGAPRODUCTDPF_KEY  =  $00039424 
VGAEXTRALORESLACEDPF_KEY=  $00031405 
VGALORESLACEDPF_KEY  =  $00039405 
VGAPRODUCTLACEDPF_KEY  =  $00039425 
VGAEXTRALORESDPF2_KEY  =  $00031444 
VGALORESDPF2_KEY  =  $00039444 
VGAPRODUCTDPF2_KEY  =  $00039464 
VGAEXTRALORESLACEDPF2_KEY=$00031445 
VGALORESLACEDPF2_KEY  =  $00039445 
VGAPRODUCTLACEDPF2_KEY  =  $00039465 
VGAEXTRAHALFBRITE_KEY  =  $00031084 
VGAEXTRAHALFBRITELACE_KEY =$00031085 


; ExtraLoRes-DblPf 

;DualPlayf ield 

; Productivity-DblPf 

;XLoRes-ILace-DblPf 

; Interlace-DblPf 

; Prod-ILace-DblPf 

;XLoRes-DblPf2 

;DualPlayfield2 

; Productivity-DblPf 2 

;XLoRes-ILace-DblPf2 

; Interlace-DblPf 2 

; Prod-ILace-DblPf 2 

; ExtraHalf brite 

;EHB-Interlace 


A2024_MONITOR_ID 

A2  0  2  4TENHERTZ_KEY 

A2 0 2 4 F I FTEENHERTZ_KEY 


$00041000  /monochrome  monitor 
$00041000  ;10  Hz  mode 
$00049000  ;15  Hz  mode 


PROTO_MONITOR_ID 


=  $00051000  /prototype 


Dec  Hex  STRUCTURE  tPoint 
0   $0  WORD  tpt_x 
2   $2  WORD   tpt_y 
4   $4  LABEL  tpt_SIZEOF 


0  ; resolution  per  point 


Dec  Hex  STRUCTURE  AnalogSignallnterval, 0 
0   $0  UWORD  asi_Start 
2   $2  UWORD  asi_Stop 
4   $4  LABEL  asi_SIZEOF 

Dec  Hex  STRUCTURE  SpecialMonitor, XLN_SIZE 
24  $18  UWORD  spm_Flags 
26  $1A  APTR   spm_do_monitor 
3  0  $1E  APTR   spm_reservedl 
34  $22  APTR   spm_reserved2 
38  $26  APTR   spm_reserved3 
42  $2A  STRUCT  spmjiblank, asi_SIZEOF 
46  $2E  STRUCT  spm_vblank, asi_SIZEOF 
50  $32  STRUCT  spm_hsync, asi_SIZEOF 
54  $36  STRUCT  spm_vsync, asi_SIZEOF 
58  $3A  LABEL   spm_SIZEOF 

Dec  Hex  STRUCTURE  MonitorSpec, XLN_SIZE 
24  $18  UWORD  ms_Flags 
26  $1A  LONG   ms_ratioh 
3  0  $1E  LONG   ms_ratiov 
34  $22  UWORD  ms_total_rows 
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3  6  $24  UWORD 

ms_total_colorclocks 

38  $26  UWORD 

ms_DeniseMaxDisplayColumn 

40  $28  UWORD 

ms_BeamCon0 

42  $2A  UWORD 

ms_min_row 

44  $2C  APTR 

ms_Special 

48  $30  UWORD 

ms_OpenCount 

50  $32  APTR 

ms_trans  form 

54  $36  APTR 

ms_translate 

58  $3A  APTR 

ms_scale 

62  $3E  UWORD 

ms_xoffset 

64  $40  UWORD 

ms_yoffset 

66  $42  STRUCT 

ms_LegalView, ra_SIZEOF 

74  $4A  APTR 

ms_maxoscan 

78  $4E  APTR 

ms_videoscan 

82  $52  UWORD 

ms_DeniseMinDisplayColumn 

84  $54  UWORD 

ms_DisplayCompat ible 

86  $56  STRUCT 

ms_DisplayInfoDataBase, LH_SIZE 

100  $64  STRUCT 

ms_DIDBSemaphore , SS_SIZE 

146  $92  ULONG 

ms_reserved0 0 

150  $96  ULONG 

ms_reserved0 1 

154  $9A  LABEL 

ms_SIZEOF 

MSB_REQUEST_NTSC  =  0, 
MSB_REQUEST_PAL  =  1, 
MSB_REQUEST_SPECIAL  =  2, 
MSB_REQUEST_A2024    =  3, 


MSF_REQUEST_NTSC  =  1 
MSF_REOUEST_PAL  =  2 
MSF_REQUEST_SPECIAL  =  4 
MSF_REQUEST_A2024    =  8 


STANDARD_VIEW_X 

STANDARD_VIEW_Y 

Dec 

Hex  STRUCT! 

34 

$22  APTR 

38 

$26  APTR 

42 

$2A  APTR 

46 

$2E  APTR 

50 

$32  APTR 

54 

$36  APTR 

58 

$3A  APTR 

62 

$3E  APTR 

66 

$42  APTR 

70 

$46  APTR 

74 

$4A  STRUCT 

96 

$60  STRUCT 

118 

$76  STRUCT 

140 

$8C  STRUCT 

154 

$9A  APTR 

158 

$9E  UWORD 

160 

$A0  BYTE 

$81 


$2C 


RE  GfxBase,LIB_SIZE 
gb_ActiView 
gb_copinit 
gb_cia 
gb_blitter 
gb_LOFlist 
gb_SHFlist 
gb_blthd 
gb_blttl 
gb_bsblthd 
gb_bsblttl 
gb_vbsrv, IS_SIZE 
gb_timsrv, IS_SIZE 
gb_bltsrv, IS_SIZE 
gb_TextFonts , LH_SIZE 
gb_DefaultFont 
gb_Modes    ;bltcon0 
gb_VBlank 


;base  structure 

.•active  View 

;Copper  start  list 

;CIA 

;Blitter 

; current  Copper  list 

/current  Copper  list 

;bltnode 
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161 

SA1  BYTE 

162 

$A2  UWORD 

164 

$A4  WORD 

166 

$A6  BYTE 

167 

$A7  BYTE 

168 

$A8  WORD 

170 

$AA  WORD 

172 

$AC  WORD 

174 

$AE  STRUCT 

188 

SBC  APTR 

192 

$C0  STRUCT 

206 

$CE  WORD 

208 

$D0  APTR 

212 

$D4  WORD 

214 

$D6  WORD 

216 

$D8  WORD 

218 

$DA  WORD 

220 

$DC  WORD 

222 

$DE  WORD 

224 

$E0  APTR 

228 

$E4  APTR 

232 

$E8  WORD 

234 

$EA  WORD 

236 

$EC  UBYTE 

237 

$ED  STRUCT 

242 

$F2  STRUCT 

244 

$F4  STRUCT 

27  6 

$114  STRUCT 

308 

$134  STRUCT 

340 

$154  WORD 

342 

$156  WORD 

344 

$158  WORD 

346 

$15A  APTR 

350 

$15E  UWORD 

352 

$160  UWORD 

354 

$162  UBYTE 

355 

$163  UBYTE 

356 

$164  STRUCT 

372 

$174  APTR 

376 

$178  WORD 

378 

$17 A  WORD 

380 

$17C  APTR 

384 

$180  STRUCT 

398 

$18E  APTR 

402 

$192  APTR 

406 

$196  APTR 

410 

$19A  APTR 

414 

$19E  APTR 

gb_Debug 

gb_BeamSync 

gb_sy s t  em_bp 1 conO 

gb_SpriteReserved 

gb_bytereserved 

gb_Flags 

gb_BlitLock 

gb_BlitNest 

gb_BlitWaitQ, LH_SIZE 

gb_BlitOwner 

gb_TOF_WaitQ, LH_SIZE 

gb_DisplayFlags 

gb_SimpleSprites 

gb_MaxDi  splayRow 

gb_MaxDisplayColumn 

gb_NormalDisplayRows 

gb_NormalDisplayColumns 

gb_Norma 1 DPMX 

gb_NormalDPMY 

gb_LastChanceMemory 

gb_LCMptr 

gb_MicrosPerLine  /microseconds  times  256 

gb_MinDisplayColumn 

gb_ChipRevBitsO   ;new  Agnus/Denise 

gb_crb_reserved, 5 

gb_monitor_id, 2 

gb_hedley , 4*8 

gb_hedley_sprites,  4*8 

gb_hedley_spritesl,  4*8 

gb_hedley_count 

gb_hedley_f lags 

gb_hedley_tmp 

gb_hash_table 

gb_current_tot_rows 

gb_current_tot_cclks 

gb_hedley_hint 

gb_hedley_hint2 

gb_nreserved, 4*4 

gb_a2024_sync_raster 

gb_control_delta_pal 

gb_control_delta_ntsc 

gb_current_monitor 

gb_MonitorList,LH_SIZE 

gb_default_monitor 

gb_MonitorListSemaphore 

gb_DisplayInfoDataBase 

gb_Ac  t  iVi  ewCpr Semaphore 

gb_UtilityBase 
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418  $1A2  APTR    gb_ExecBase 
422  $1A6  LABEL    gb_SIZE 

OWNBLITTERn  =  0  ;Blitter  occupied 
QBOWNERn     =  1  ;Blitter  occupied  by  queue 

GFXB_BIG_BLITS  =  0  ;ChipRevBitsO 
GFXB_HR_AGNUS   =  0  ;HiRes  Agnus 
GFXB_HR_DENISE  =  1  ;HiRes  Denise 

NTSCn  =  0  /display  bits 

GENLOCn  =  1 

PALn  =  2 

TODA_SAFEn  =  3 

BLITMSG_FAULTn    =  2 

Dec  Hex  STRUCTURE  XLN, 0  ; graphics  node 


0 

$0  APTR 

XLN_SUCC 

4 

$4  APTR 

XLN_PRED 

8 

$8  UBYTE 

XLN_TYPE 

9 

$9  BYTE 

XLN_PRI 

10 

$A  APTR 

XLN_NAME 

14 

$E  UBYTE 

XLN_SUBSYSTEM 

15 

$F  UBYTE 

XLN_SUBTYPE 

16 

$10  LONG 

XLN_LIBRARY 

20 

$14  LONG 

XLN_INIT 

24 

$18  LABEL 

XLN_SIZE 

SS_GRAPHICS  =  $02  ;GfxSemaphore 

VIEW_EXTRA_TYPE  =  1 
VIEWPORT_EXTRA_TYPE  =  2 
SPECIAL_MONITOR_TYPE  =  3 
MONITOR_SPEC_TYPE     =  4 

VTAG_END_CM  =  $00000000 

VTAG_CHROMAKEY_CLR  =  $80000000 
VTAG_CHROMAKEY_SET  =  $80000001 
VTAG_BITPLANEKEY_CLR  =  $80000002 
VTAG_BITPLANEKEY_SET  =  $80000003 
VTAG_BORDERBLANK_CLR  =  $80000004 
VTAG_BORDERBLANK_SET  =  $80000005 
VTAG_BORDERNOTRANS_CLR  =  $80000006 
VTAG_BORDERNOTRANS_SET  =  $80000007 
VTAG_CHROMA_PEN_CLR  =  $80000008 
VTAG_CHROMA_PEN_SET  =  $80000009 
VTAG_CHROMA_PLANE_SET   =  $8000000A 
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VTAG_ATTACH_CM_SET 

= 

$8000000B 

VTAG_NEXTBUF_CM 

= 

$8000000C 

VTAG_BATCH_CM_CLR 

= 

$8000000D 

VTAG_BATCH_CM_SET 

= 

$8000000E 

VTAG_NORMAL_DISP_GET 

= 

$8000000F 

VTAG_NORMAL_DISP_SET 

= 

$80000010 

VTAG_COERCE_DISP_GET 

= 

$80000011 

VTAG_COERCE_DISP_SET 

= 

$80000012 

VTAG_VIEWPORTEXTRA_GET  = 

$80000013 

VTAG_VIEWPORTEXTRA_SET  = 

$80000014 

VTAG_CHROMAKEY_GET 

= 

$80000015 

VTAG_BITPLANEKEY_GET 

= 

$80000016 

VTAG_BORDERBLANK_GET 

= 

$80000017 

VTAG_BORDERNOTRANS_GET  = 

$80000018 

VTAG_CHROMA_PEN_GET 

= 

$80000019 

VTAG_CHROMA_PLANE_GET   = 

$8000001A 

VTAG_ATTACH_CM_GET 

= 

$8000001B 

VTAG_BATCH_CM_GET 

= 

$8000001C 

VTAG_BATCH_ITEMS_GET 

= 

$8000001D 

VTAG_BATCH_ITEMS_SET 

= 

$8000001E 

VTAG_BATCH_ITEMS_ADD 

= 

$8000001F 

VTAG_VPMODEID_GET 

= 

$80000020 

VTAG_VPMODEID_SET 

= 

$80000021 

VTAG_VPMODEID_CLR 

= 

$80000022 

VTAG_USERCLI P_GET 

= 

$80000023 

VTAG_USERCLI P_SET 

= 

$80000024 

VTAG_USERCLI P_CLR 

= 

$80000025 

GENLOCK_VIDEO 

s: 

.•composite  video  signal 

V_LACE 

$' 

; Interlace 

V_SUPERHIRES 

$2C 

;SuperHiRes 

V_PFBA 

$4C 

; switch  Playfields 

V_EXTRA_HALFBRITE  = 

$8( 

;Halfbrite 

GENLOCK_AUDIO 

$10( 

; audio  signal 

V.DUALPF 

$400  ;DualPlayfield 

V_HAM              = 

$800  ;Hold  And  Modify 

V_EXTENDED_MODE 

$1000  ; extended  structure 

V_VP_HIDE 

52000  ;hide  Viewport 

V_SPRITES 

54000  /Sprite  DMA  activated 

V_HIRES 

58000  ;HiRes 

EXTENDJVSTRUCT 


$1000 


VPF_DENISE 

VPF_A2024 

VPF_AGNUS 

VPF_TENHZ 

VPF_ILACE 


$80 
$40 
$20 
$20 
$10 
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Dec  Hex 

STRUCTURE  ColorMap, 0 

0   $0 

BYTE 

cm_Flags 

1   $1 

BYTE 

cm_Type 

2   $2 

WORD 

cm_Count 

4   $4 

APTR 

cm_ColorTable 

8   $8 

APTR 

cm_vpe 

12   $C 

APTR 

cm_Tr anspar ency B  its 

16  $10 

BYTE 

cm_TransparencyPlane 

17  $11 

BYTE 

cm_reservedl 

18  $12 

WORD 

cm_reserved2 

20  $14 

APTR 

cm_vp 

24  $18 

APTR 

cm_NormalDisplayInfo 

28  $1C 

APTR 

cm_CoerceDisplayInfo 

32  $20 

APTR 

cm_batch_items 

36  $24 

LONG 

cm_VPModeID 

40  $28 

LABEL 

cm_SIZEOF 

COLORMAPJTYPE. 

_V1_2  =  0  ;old  ColorMap 

COLORMAPJTYPE. 

_V36   =  1  ;new  ColorMap 

COLORMAPJTRANSPARENCY    =  $01 

COLORPLANE_TRANSPARENCY  =  $02 

BORDER_BLANKING          =  $04 

BORDER_NOTRANSPARENCY    =  $08 

VIDEOCONTROL_BATCH       =  $10 

USER_COPPER_CLIP         =  $20 

Dec  Hex 

STRUCTURE  ViewPort.O 

0   $0 

LONG 

vp_Next 

4   $4 

LONG 

vp_ColorMap 

8  $8 

LONG 

vp_DspIns 

12   $C 

LONG 

vp_SprIns 

16  $10 

LONG 

vp_ClrIns 

20  $14 

LONG 

vp_UCopIns 

24  $18 

WORD 

vp_DWidth 

26  $1A  WORD 

vp_DHeight 

28  $1C 

WORD 

vp_DxOffset 

30  $1E  WORD 

vp_DyOf fset 

32  $20 

WORD 

vp_Modes 

34  $22 

BYTE 

vp_SpritePriorities 

35  $23 

BYTE 

vp_Ext  endedMode s 

36  $24 

APTR 

vp_RasInfo 

40  $28 

LABEL 

vp_SIZEOF 

Dec  Hex  STRUCTURE  View, 0 
0   $0  LONG    v_ViewPort 
4   $4  LONG    v_LOFCprList 
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8   $8  LONG 


v_SHFCprList 


12   $C  WORD  v_DyOffset 

14   $E  WORD  v_DxOffset 

16  $10  WORD  v_Modes 

18  $12  LABEL  v_SIZEOF 

Dec  Hex  STRUCTURE  ViewExtra,XLN_SIZE 
24  $18  APTR    ve_View 
28  $1C  APTR    ve_Monitor 
32  $20  LABEL   ve_SIZEOF 

Dec  Hex  STRUCTURE  ViewPortExtra,XLN_SIZE 
24  $18  APTR    vpe_ViewPort 
28  $1C  STRUCT  vpe_DisplayClip,ra_SIZEOF 
36  $24  LABEL   vpe_SIZEOF 

Dec  Hex  STRUCTURE  collTable, 0 
0   $0  LONG    cp_collPtrs,16 
64  $40  LABEL   cp_SIZEOF 


Dec  Hex  STRUCTURE  Raslnfo, 0 


0  $0  APTR 

4  $4  LONG 

8  $8  WORD 

10  $A  WORD 

12  $C  LABEL 


ri_Next 
ri_BitMap 
ri_RxOf fset 
ri_RyOf fset 
riSIZEOF 


2.  General  Blitter  Control 


IBitMapScalT 


Change  the  size  of  bit-map  contents  | 


Call:  BitMapScale  (  bitScaleArgs   ) 

-678 (A6)  a0 

STRUCT  BitScaleArgs   *bitScaleArgs 

Function:  Copies  a  portion  of  a  bit-map  to  another  bit-map,  changing 
the  size  to  correspond  to  the  size  of  the  destination  bit- 
map. 


Parameters:  bitScaleArgs 


Structure  with  the  following  parameters: 

bsa_srcX,  bsa_srcY  Upper  left  corner  of  the 
source  bit-map. 
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bsa_srcWidth,  bsa_srcHeight 

Size  of  source  bit-map. 

bsa_destX,  bsa_destY 

Position  in  the  destination  bit- 
map. 

bsa_destWidth,  bsa_destHeight 

New  size  (result) 

bsa_xSrcFactor:bsa_xDestFactor 

Scaling  factor,  corresponds  with 
bsa_srcWidth:bsa_destWidth; 
Range:  1..16383. 

bsa_ySrcFactor:bsa_yDestFactor 
Same  for 
bsa_srcHeight:bsa_destHeight. 

bsa_srcBitMap 

Source  bit-map 

bsa_destBitMap 

Destination   bit-map   (may  not 
overlap  with  srcBitMap). 

bsa_flags       0  (not  yet  supported) 

Result:  destWidth  and  destHeight  are  filled  with  the  new  size. 

Example:  Double  the  size  of  an  image.  A  LoRes  bit-map  in  320*256 
pixel  format  is  copied  to  fill  a  bit-map  in  640*512  HiRes 
Interlace  format.  The  size  change  is  accomplished  as 
follows: 

bsa_DestWidth=bsa_SrcWidth*bsa_XDestFactor/bsa_XSrcFactor 
bsa_DestHeight=bsa_SrcHeight*bsa_YDestFactor/bsa_YSrcFactor 

In  our  example: 

bsa_DestWidth  =  320  *  2  /  1  =  640 
bsa_DestHeight  =  256  *  2  /  1  =  512 
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Here  is  the  simple  demo  routine: 


movea . 1  _Gf xBase , a6 

lea     _BitScaleArgs(pc) ,a0 

jsr     _BitMapScale(a6) 


_BitScaleArgs 

dew  0,0  ;bsa_SrcX,    bsa_SrcY 

dew  320,256  ;bsa_SrcWidth,    bsa_SrcHeight 

dew  1,1  ;bsa_XSrcFactor,    bsa_YSrcFactor 

dew  0,0  ;bsa_DestX,    bsa_DestY 

dew  0,0  ;bsa_DestWidth,    bsa_DestHeight 

dew  2,2  ;bsa_XDestFactor,bsa_YDestFactor 

del  _LoResBitMap  ;bsa_SrcBitMap 

del  _HiResILaceBitMap    ;bsa_DestBitMap 

del  0  ;bsa_Flags 

dew  0,0  ;bsa_XDDA,    bsa_YDDA 

del  0,0  ;bsa_Reservedl,    bsa_Reserved2 


IBItBitMap" 


Copy  a  portion  of  a  bit-map  | 


Call: 


planecnt  =  BltBitMaplSrcBitMap,  SrcX,  SrcY,  DstBitMap, 
DO  -30(A6)    AO  D0:16  Dl:16  Al 

DstX,  DstY,  SizeX,  SizeY,  Minterm,  Mask,  TempA) 
D2:16  D3:16  D4:16   D5:16   D6 : 8      D7 : 8   A2 


ULONG  planecnt 

STRUCT  BitMap  *SrcBitMap, DstBitMap 

WORD   SrcX , SrcY , DstX, DstY, SizeX, SizeY 

UBYTE  Minterm,Mask 

APTR   TempA 

Copies  part  of  a  bit-map  to  the  given  position  in  another 
bit-map.  Both  bit-maps  can  be  the  same  and  the  ranges  may 
overlap.  If  a  bit-plane  address  is  set  to  0,  it  is  handled  like 
an  empty  bit-plane.  If  the  bit-plane  address  is  -1,  it  is 
handled  like  a  filled  bit-plane. 


Parameters:  SrcBitMap  Source  bit-map 


Function: 


DstBitMap 


Destination  bit-map 
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SrcX,  SicY  Coordinates  in  the  source  bit-map. 

DstX,DstY 

Coordinates  in  the  destination  bit-map. 

SizeX,SizeY 

Size  of  the  region  to  be  copied. 

Minterm      Logical  combination  of  source  and  destination: 

Blitter  source  A  is  filled  within  the  region. 
Blitter  source  B  is  the  source. 
Blitter  sources  C  and  D  are  the  destination. 
$C0  copies,  $30  copies  the  inverted  source, 
$50  inverts  only  the  destination,  etc. 

Mask  Bit  mask  for  destination  bit-plane. 

TempA        Buffer  for  one  line  (source  A)  that  must  be 
scrolled  horizontally  if  the  regions  overlap. 

Result:  Number  of  affected  bit-planes. 

IBltBitMapRastPort  Copy  a  bit-map  range  to  a  RastPortl 

Call:  BltBitMapRastPort 

(srcbm,srcx,srcy,destrp,destX,destY,sizeX,sizeY, minterm) 

-606 (A6)         aO     dO    dl    al   d2    d3    d4   d5  d6 

STRUCT  BitMap  *srcbm 

WORD   srcx, srcy , destx, destY, sizeX, sizeY 

STRUCT  RastPort  *destrp 

UBYTE  minterm 

Function:     Similar  to  BltBitMapO,  except  that  the  destination  is  the 
given  RastPort  and  a  mask  cannot  be  used. 

Parameters:  srcbm         Source  bit-map 

srcx,srcy     Position  in  the  source  bit-map. 
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destrp 


Destination  RastPort 


destX,destY 


Position  in  RastPort 

sizeX,sizeY 

Size  of  range 

minterm      Logical  combination 


IBItClear 


Clear  memory  block  (ChipR AM)  | 


Call: 


BltClearf  memBlock,  bytecount,  flags  ) 


-300 (A6)   al 


dO 


dl 


APTR     memBlock 

ULONG  bytecount , flags 

Function:     Clears  a  memory  block  in  ChipRAM. 

Parameters:  memBloc    Address  of  block 

flags  Bit  0:1  Call  WaitBlit() 

Bit  1:0  bytecount  =  size  of  range 

1  bytecount  =  lines 

« 1 6+B  y  tesPerLine 
Bit  2: 1  bytecount  =  full  value«16+size 

of  range 

|  BltMaskBitMap RastPort     Copy  bit-map  to  a  RastPort  with  a  mask  | 


Call: 


BltMaskBitMapRastPort 

(srcbm, srcx, srcy,  destrp,  destX,destY,sizeX,  si2eY,minterm,bltmask) 

-636  (A6)  aO    do    dl    al     d2     d3    d4   d5   d6  a2 


Functions,  Parameters: 

Same  as  BltBitMapRastPort(),  with  the  addition  of  the 
address  of  a  single  bit-plane  (bltmask)  in  which  the  affected 
bits  are  set. 
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|  BltPattern  Blit  using  a  mask  j 

Coll:  BltPattern (rp,  mask,  xl,  yl,  maxx,  maxy,  bytecnt) 

-312  (A6)    al   aO    dO   dl   d2    d3     d4 

STRUCT  RastPort  *rp 

APTR   mask 

SHORT  xl,yl, maxx, maxy, bytecnt 

Function:  Blits  a  rectangular  region  at  a  given  position  via  a  mask, 
using  the  Drawmode  and  Areafill  pattern  entries  from  the 
RastPort. 

Parameters:  rp  RastPort 

mask  MaskBitPlane  or  0  (rectangle) 

xl,yl  Position  in  RastPort 

maxx,maxy 

Size  of  range 

bytecnt       Bytes  per  line  in  the  mask 

|  BUT  em  plate  Copy  a  rectangular  region  to  the  RastPort  | 

Call:  BlcTemplatelSrcTemplate,   SroX,   SrcMod,   rp,    DstX,   DsCY,   SizeX,   sizoV) 

-36  (A6)  AO  DO  Dl  Al     D2  D3  D4  D5 

APTR       SrcTemplate 

WORD        SroX, SrcMod,  DstX,  DstY,  SlzeX,  SlzeY 

STRUCT  RastPort  *rp 

Function:  Copies  a  rectangular  portion  of  a  bit-plane  with  the 
selected  color  and  Drawmode  to  a  given  position  in  a 
RastPort. 

Parameters:  SrcTemplate 

Address  of  the  first  word  in  the  Bitlmage. 

SrcX  X  bit  offset  from  SrcTemplate  (0..15). 

SrcMod      Bytes  per  line  in  the  Bitlmage. 
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rp  Destination  RastPort. 

DstX,  DstY 

Coordinates  in  RastPort. 

SizeX,  SizeY 

Size  of  range. 

IClipBlit  BltBitMapQ,  with  layers] 

Call.'  ClipBlit(Src,  SrcX,  SrcV,  Dest,   DestX,   DestY,  XSize,  YSize,   Minterm) 

-552 (A6)   aO       dO         dl         al  d2  d3  d4  d5  d6 

STRUCT  RastPort  *Src,*Dest 

WORD      SrcX.SrcY, DestX, DestY.XSize, YSize 

UBYTE  Minterm 

Function:  Same  as  BltBitMapO,  except  that  the  ClipRects  are 
considered  here.  With  windows,  this  function  must  be 
called  instead  of  BltBitMapO. 

Parameters:  Src  Source  RastPort 

SrcX,SrcY  Position  in  source  RastPort. 

Dest  Destination  RastPort 

DestX,DestY 

Position  in  destination  RastPort. 

XSize.YSize 

Size  of  range 

Minterm     Logical  combination  (B=source, 
C=destination) 

ICopySBitMap  Copy  SuperBitMap  range  to  a  layer  | 

Call:  CopySBitMap(   layer   ) 

-450 (A6)  aO 

STRUCT  Layer   * layer 
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Function:  Opposite  of  SyncSBitMapO  -  copies  the  current  excerpt  of 
a  SuperBitMap  to  the  given  SuperBitMap  layer. 

Parameters:  layer  SuperBitMap  layer  (must  be  allocated  with 

LockLayerROMO) 

IDisownBlitter  Free  Blitterl 

Call:  DisownBlitter  () 

-462 (A6) 

Function:     Frees  the  Blitter  for  use  by  other  programs. 

|  OwnBlitter  Obtain  use  of  Blitter  | 

Call:  OwnBlitter  () 

-456(A6) 

Function:  Prevents  other  programs  from  using  the  Blitter.  The  Blitter 
becomes  available  only  after  it  finishes  its  current  operation 
(seeWaitBlitO). 

IQBlit  Enter  BltNode  in  the  Blitter  list | 

Call:  QBlit(  bp   ) 

-276 (A6)    al 

STRUCT  bltnode  *bp 

Function:  Enters  a  BltNode  in  the  wait  queue  of  the  Blitter.  If  the 
indicated  routine  is  called,  the  Blitter  stops  work  and 
becomes  available,  meaning  it  can  be  directly  programmed. 
The  routine  must  be  executable  in  both  supervisor  and  user 
modes. 

Parameters:  bp  Initialized  BltNode 

IQBSBlit  QBlit  with  raster  synchronization 


Call:  QBSBlit(  bsp  ) 

-294 (A6)    al 
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STRUCT  bltnode  *bsp 

Function:  Same  as  QBlit(),  except  that  the  routine  is  only  called  when 
the  monitor  beam  reaches  a  certain  position.  BltNodes 
entered  with  QBSBlit()  take  priority  over  QBlit()  BltNodes. 
Access  by  several  tasks  can  lead  to  synchronization  errors 
or  true  timing  problems. 

Parameters:  bsp  Initialized  BltNode 

IScalerDiv  Calculate  scaling  | 

Call:  result  =  ScalerDiv( factor,  numerator,  denominator) 

dO       -684 (A6)   dO      dl         d2 

UWORD  result , factor, numerator , denominator 

Function:  Calculates  factor*numerator/denominator  just  like 
BitMapScale().  For  example,  the  new  width  can  be 
calculated  as  width*XDestFactor/XSrcFactor. 

Parameters:  factor         Width  or  height  from  BitMapScale(). 

numerator  ?DestFactor 

denominator 

?SrcFactor 

Result:  factor*numerator/denominator 

IScrollRaster  Scroll  a  rectangular  range  | 

Call:  ScrollRaster(  rp,  dx,  dy,  xmin,  ymin,  xmax,  ymax) 

-396  (A6)      al  dO  dl  d2    d3    d4    d5 

STRUCT  RastPort  *rp 

WORD  dx,dy, xmin, ymin, xmax, ymax 

Function:  Moves  the  contents  of  a  rectangular  range  by  the  given 
delta  value  in  the  direction  of  coordinates  (0,0).  The  bug 
that  occurred  in  Kick  1.x,  if  the  TmpRas  structure  was 
missing,  has  been  fixed. 
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Parameters:  rp  RastPort 

dx.dy  Delta  value  (right  and  down  NEGATIVE) 

xmin.ymin   Upper  left  comer 

xmax,ymax 

Lower  right  corner 

ISyncSBitMap  Copy  layer  contents  to  a  Super BitMapl 

Call:  SyncSBitMap(   layer   ) 

-444 (A6)  aO 

STRUCT  Layer  * layer 

Function:  Copies  the  contents  of  a  SuperBitMap  layer  to  the  current 
position  of  the  SuperBitMap. 

Parameters:  layer  SuperBitMap  layer  (locked) 

[WaltBlit  Wait  for  the  Blitterj 

Call:  WaitBlitO 

-228 (A6) 

Function:  Waits  until  the  Blitter  finished  its  current  work.  This 
function  is  normally  used  after  OwnBlitter()  and/or  before 
DisownBlitter(). 

Dec  Hex  STRUCTURE  BitMap.O  ;BitMap 

0   $0  WORD    bm_BytesPerRow  ; bytes  per  row 

2  $2  WORD    bm_Rows  ;rows 

4  $4  BYTE    bm_Flags  ; Flags 

5  $5  BYTE    bm_Depth  ; number  of  BitPlanes 

6  $6  WORD    bm_Pad 

8  $8  STRUCT  bm_Planes,8*4   ; PlanePointer 
40  $28  LABEL   bm_SIZEOF 

Dec  Hex  STRUCTURE  BitScaleArgs, 0  ;BitMapScale ()  argument 
2   $2  UWORD   bsa_SrcX         /source  position 
4  $4  UWORD   bsa_SrcY 

6  $6  UWORD   bsa_SrcWidth     ,- source  size 
8  $8  UWORD   bsa_SrcHeight 
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10 

$A  UWORD 

bsa_XSrcFactor 

; denominators 

12 

$C  UWORD 

bsa_YSrcFactor 

14 

$E. UWORD 

bsa_DestX 

; destination  position 

16 

$10  UWORD 

bsa_DestY 

18 

$12  UWORD 

bsa_DestWidth 

; result 

20 

$14  UWORD 

bsa_DestHeight 

22 

$16  UWORD 

bsa_XDestFactor 

; numerators 

24 

$18  UWORD 

bsa_YDestFactor 

26 

$1A  APTR 

bsa_SrcBitMap 

; source  BitMap 

30 

$1E  APTR 

bsa_DestBitMap 

; destination  BitMap 

34 

$22  ULONG 

bsa_Flags 

;0! 

38 

$26  UWORD 

bsa_XDDA 

40 

$28  UWORD 

bsa_YDDA 

42 

$2A  LONG 

bsa_Reservedl 

46 

$2E  LONG 

bsa_Reserved2 

50 

$32  LABEL 

bsa_SIZEOF 

3.  Refresh  Functions 


|AndRectRegion 


Preserve  contents  of  a  rectangle] 


Call:  AndRectRegion  (region,  rectangle) 

-504 (A6)  aO  al 

STRUCT  Region  *region 
STRUCT  Rectangle  *rectangle 

Function:     Deletes  everything  in  the  region  outside  of  the  given 
rectangle. 

Parameters:  region        Region  structure 

rectangle     Rectangle  structure 


AndRegionRegion 


Trim  a  region  | 


Call:  status       AndRegionRegion (regionl,region2) 

dO  -624 (A6)  aO  al 

BOOL  status 

STRUCT  Region  *regionl, *region2 

Function:     Cut  off  surfaces  from  region2  that  are  not  part  of  region  1 . 


283 


3.  Programming  with  AmigaOS  2x 


Parameters:  regionl  Mask  region 

region2  Destination  region 

Result:  0  Error  (no  memory) 

IClearRectRegion  Clear  a  rectangle  within  a  regionl 

Call:  status  =  ClearRectRegion (region, rectangle) 

dO  -522 (A6)  aO  al 

BOOL  error 

STRUCT  Region  *region 

STRUCT  Rectangle  *rectangle 

Function:     Cuts  a  rectangle  out  of  a  region. 

Parameters:  region         Region  containing  the  rectangle. 

rectangle    Rectangle  to  be  deleted. 

Result:  0  Error  (no  memory) 

IClearRegion  Clear  all  rectangles  within  a  regionl 

Call:  ClearRegion  (region) 

-528 (A6)  aO 

STRUCT  Region  *region 

Function:      Clears  an  entire  region. 

Parameters:  region         Region  to  be  cleared 

fDisposeRegion  Free  regionl 

Call:  DisposeRegion  (region) 

-534 (A6)  aO 

STRUCT  Region  *region 
Function:     Frees  the  memory  of  a  region. 
Parameters:  region         Region  structure 
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|NewRegion  Get  a  Region  structure | 

Call:  region       NewRegion  ( ) 

dO  -516 (A6) 

STRUCT  Region  *region 

Function:      Allocates  memory  for  a  Regions  structure  and  initializes  it. 

Result:  Region  structure  or  0. 

IQrRectRegion  Insert  rectangle  into  a  region! 

Call:  status  =  OrRectRegion (region, rectangle) 

dO       -510 (A6)     aO     al 

BOOL   status 

STRUCT  Region  *region 

STRUCT  Rectangle  *rectangle 

Function:      Inserts  the  given  rectangle  (not  contained  in  the  region) 
into  the  given  region. 

Parameters:  region  Region  structure 

rectangle  Rectangle  structure 

Result:  0  Error 

IQrRegionRegion  Join  Region  structures! 

Call:  status       OrRegionRegion(regionl,region2) 

dO  -612 (A6)  aO  al 

BOOL        status 

STRUCT  Region  *regionl, *region2 

Function:      Adds  region  1  to  region2. 

Parameters:  region  1  ,region2 

Region  structures 
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Result:  0  Error 

IXorRect Region  Exclusive  OR  combination  of  two  areas  | 

Call:  status  =  XorRectRegion  (region,  rectangle) 

dO  -558 (A6)  aO  al 

BOOL       status 

STRUCT  Region  *region 

STRUCT  Rectangle  *rectangle 

Function:  Adds  the  given  rectangle  (not  contained  in  the  region)  to 
the  given  region,  and  deletes  the  part  of  the  region  common 
to  both. 

Parameters:  region  Region  structure 

rectangle  Rectangle  structure 

Result:  0  Error 

IXorRegionRegion  Exclusive  OR  combination  of  two  regions] 

Call:  status  =  XorRegionRegion(regionl,region2) 

dO  -618 (A6)  aO  al 

BOOL        status 

STRUCT  Region  *regionl, *region2 

Function:  Adds  one  region  to  the  other  and  deletes  the  overlapping 
area. 

Parameters:  regionl,region2 

Regions  to  be  combined 

Result:  0  Error 

Dec  Hex  STRUCTURE  Rectangle, 0  ; rectangle 
0  $0  WORD  ra_MinX         ; dimens ions 
2   $2  WORD  ra_JlinY 
4  $4  WORD  ra_MaxX 
6  $6  WORD  ra_MaxY 
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8   $8  LABEL  ra_SIZEOF 

Dec  Hex  STRUCTURE  Rect32,0  ;32  bit  rectangle 

0   $0  LONG  r32_MinX     ; dimensions 

4  $4  LONG  r32_MinY 

8  $8  LONG  r32_MaxX 
12  $C  LONG  r32_MaxY 
16  $10  LABEL  r32_SIZEOF 

Dec  Hex  STRUCTURE  Region, 0 

0   $0  STRUCT  rg_bounds,ra_SIZEOF 
8  $8  APTR   rg_RegionRectangle 
12   $C  LABEL  rg_SIZEOF 

Dec  Hex  STRUCTURE  RegionRectangle, 0 
0   $0  APTR   rr_Next 
4   $4  APTR   rr_Prev 
8   $8  STRUCT  rr_bounds,ra_SIZEOF 
16  $10  LABEL  rr_SIZEOF 

4.  Data  Structures 

jAllocRaster  Allocate  memory  for  a  bit-plane  1 

Call:  planeptr  =  AllocRaster(  width,   height   ) 

dO  -492(A6)  d0:16      dl:16 

APTR       planeptr 
USHORT  width, height 

Function:     Allocates  the  ChipRAM  required  for  a  bit-plane  of  the 
given  size. 

Parameters:  width  Bit-plane  width  in  pixels. 

height         Bit-plane  height  in  pixels. 

Result:  Address  of  memory  block  or  0. 

|  AttemptLockLayerRom  Attempt  to  lock  a  layer  | 

Call:  gotit  =  AttemptLockLayerRom  (   layer   ) 

dO  -654 (A6)  a5 

BOOLEAN  gotit 
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STRUCT  Layer  * layer 

Function:      Attempts  to  lock  a  layer  with  exclusive  access  rights. 

Parameters:  layer  Layer  structure 

Result:  0  No  access  to  layer. 

IFreeColorMap  Free  a  ColorMap! 

Call:  FreeColorMap  (   colormap   ) 

-576 (A6)  aO 

STRUCT  ColorMap  *colormap 

Function:      Frees  the  memory  used  by  a  structure  allocated  with 
GetColorMap(). 

Parameters:  colormap     Address  of  the  ColorMap. 


|FreeRaster  Free  a  bit-plane 


Call:  FreeRaster(  p,   width,   height) 

-498 (A6)  aO   d0:16      dl:16 

APTR    p 

USHORT  width, height 

Function:     Frees  the  memory  used  for  a  bit-plane. 

Parameters:  p  PlaneAddress 

width  Width  in  bits 

height        Height  of  bit-plane 
IGetColorMap  Allocate  a  ColorMap  | 

Call:  cm  =  GetColorMap(   entries   ) 

dO        -570 (A6)  dO 

STRUCT  ColorMap  *cm 
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LONG  entries 

Function:     Allocates  memory  for  a  ColorMap  and  initializes  the 
structure. 

Parameters:  entries        Number  of  colors 

Result:  ColorMap  or  0. 


GetRGB4 


Allocate  a  3x4  bit  color  value] 


Call:  value  =  GetRGB4  (   colormap,    entry   ) 

dO  -582  (A6)    aO  dO 

ULONG     value 

STRUCT  ColorMap  *colormap 

LONG   entry 

Function:  Reads  the  color  value  of  a  color  number  from  the  given 
ColorMap. 

Parameters:  colormap    ColorMap  structure 

entry  Color  number  (0...) 

Result:  red  value«8+green  value«4+blue  value  (4  bits  each: 

0...15)  or  -1  (entry  not  available,  error) 

Example:  Get  the  color  values  for  the  background  color  of  a 
ViewPort  and  set  them  in  a  second  ViewPort  (Warning: 
doing  this  by  hand  could  cause  problems  with  the  new  24 

bit  ColorMaps): 


movea . 

1 

_Gf xBase, a6 

movea . 

1 

_ViewPortl,aO 

movea . 

1 

vp_ColorMap (aO ) , aO 

moveq 

#0,d0 

jsr 

_LVOGetRGB4(a6) 

tst  .w 

dO 

bmi 

_Zerror 

moveq 

#15, d3 

;mask  for  blue  value 

and.w 

d0,d3 

;blue  value 
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lsr.w 

#4,d0 

moveq 

#15, d2 

; green  value  mask 

and.w 

d0,d2 

; green  value 

lsr.w 

#4,d0 

moveq 

#15, dl 

;red  value  mask 

and.w 

dO.dl 

;red  value 

moveq 

#0,d0 

; color  number 

movea . 1  _ViewPort2 

aO 

;2nd  Viewport 

jsr 

_LVOSetRGB4(a6) 

Unit  Bit  Map" 


Initialize  a  BitMap  structure 


Call:  InitBitMap (  bm,  depth,  width,  height  ) 

-390 (A6)    aO  dO     dl     d2 

STRUCT  BitMap  *bm 

BYTE   depth 

UWORD  width , height 

Function:     Initializes  a  BitMap  structure.  The  bit-plane  addresses  are 
excluded  in  order  to  keep  the  size  of  the  structure  variable. 


Parameters:  bm 

depth 
width 


BitMap  structure  to  be  initialized. 
Number  of  bit-planes 
Width  in  bits 


height        Height  of  bit-plane 


llnitRastPorT 


Initialize  a  RastPortl 


Call:  initRastPort  (  rp  ) 

-198 (A6)      al 

STRUCT  RastPort  *rp 

Function:  Initializes  a  RastPort  structure  with  the  standard  values 
(Mask=-1,  FgPen=-l,  AOLPen=-l,  LinePtrn=-l, 
DrawMode=JAM2,  Font=Systemfont). 


Parameters:  rp 


RastPort  structure 
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llnitTmpRas  Initialize  TmpRas] 

Call:  InitTmpRas  (tmpras,  buffer,  size) 

-468 (A6)    aO      al      dO 

STRUCT  TmpRas  *tmpras 
APTR   buffer 
LONG   size 

Function:      Initializes  a  TmpRas  structure  with  a  buffer  for  intensive 
graphics  operations  (AreaEnd(),  Flood(),  Text()). 

Parameters:  tmpras  TmpRas  structure 

buffer  ChipRAM  buffer 

size  Buffer  size 

|InitView  Initialize  View  structure  | 

Call:  InitView(   view   ) 

-360(A6)      al 

STRUCT  View  *view 

Function:      Initializes  a  View  structure  with  the  standard  values. 

Parameters:  view  View  structure 

InitVPort  Initialize  ViewPort  structure] 


Call:  InitVPort  (  vp   ) 

-204 (A6)         aO 

STRUCT  Viewport   *vp 
Function:      Initializes  a  ViewPort  structure  with  the  standard  values. 
Parameters:  vp  ViewPort  structure 
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|LockLayerRom  Obtain  access  to  a  layer  | 

Call:  LockLayerRom  (   layer   ) 

-432 (A6)  a5 

STRUCT  Layer  * layer 

Function:  Obtains  exclusive  access  to  a  layer.  No  Intuition  functions 
may  be  called  during  this  time,  since  most  of  the  work  is 
done  by  the  input  Handler  Intuition(),  which  also  must  use 
locking  to  obtain  exclusive  access.  There  is  no  problem 
calling  LockLayerRom()  with  libraries  that  are  not  based 
on  a  single  task,  since  this  function  first  checks  to  see  if  the 
active  task  already  has  access  to  the  layer. 

Parameters:  layer  Layer  structure 

|SetRGB4CM  Enter  a  color] 

Call:  SetRGB4CM(cm,    n,      r,        g,        b) 

-630 (A6)      aO      dO      dl:4   d2:4   d3:4 

STRUCT  ColorMap  *cm 
SHORT  n 
UBYTE  r,g,b 

Function:  Enters  the  intensity  values  for  a  color  in  a  ColorMap.  This 
function  is  used  to  create  color  tables  before  entering  in  a 
ViewPort. 

Parameters:  cm  ColorMap 

n  Color  number  (0..  .31) 

r,g,b  4  bit  intensity  value  (0...15) 

lUnlockLayerRom  Free  a  layer | 

Call:  UnlockLayerRom  (   layer   ) 

-438 (A6)  a5 

Function:     Frees  exclusive  access  rights  to  a  layer. 
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Parameters:  layer 

Locked  layer 

NEWLOCKE 

=  1  ;new  Layer  lock 

Dec  Hex 

STRUCTURE  Layer, 0 

range  for  clipping 

0   $0 

LONG 

lr_front              , 

foreground  Layer 

4   $4 

LONG 

lr_back                , 

background  Layer 

8   $8 

LONG 

lr_ClipRect            , 

ClipRect 

12   $C 

LONG 

lr_rp                 , 

RastPort 

16  $10 

WORD 

lr_MinX 

range 

18  $12 

WORD 

lr_MinY 

20  $14 

WORD 

lr_MaxX 

22  $16 

WORD 

lr_MaxY 

24  $18 

STRUCT 

lr_reserved, 4 

reserved 

28  $1C 

WORD 

lr_priority 

priority 

30  $1E 

WORD 

lr_Flags 

Flags 

32  $20 

LONG 

lr_SuperBitMap 

BitMap 

36  $24 

LONG 

lr_SuperClipRect 

ClipRect 

40  $28 

APTR 

lr_Window 

window 

44  $2C 

WORD 

lr_Scroll_X 

BitMap  offsets 

46  $2E  WORD 

lr_Scroll_Y 

48  $30 

APTR 

lr_cr 

ClipRect 

52  $34 

APTR 

lr_cr2 

ClipRect 

56  $38 

APTR 

lr_crnew 

ClipRect 

60  $3C 

APTR 

lr_SuperSaverClipRects 

ClipRects 

64  $40 

APTR 

lr cliprects 

ClipRects 

68  $44 

APTR 

lr_LayerInfo 

•Layer Info 

72  $48 

STRUCT 

lr_Lock,SS_SIZE 

• SignalSemaphore 

118  $76 

APTR 

lr_BackFill 

•backfill  Hook 

122  $7A  ULONG 

lr_reservedl 

; reserved 

126  $7E 

APTR 

lr_ClipRegion 

; region 

130  $82 

APTR 

lr_saveClipRects 

;ClipRects 

134  $86 

STRUCT 

lr_reserved2 , 22 

; reserved  (SS_SIZE) 

156  $9C 

APTR 

lr_DamageList 

; damage  list 

160  $A0 

LABEL 

lr_SIZEOP 

Dec  Hex 

STRUCTURE   CI ipRect , 0 

0   $0 

LONG 

cr_Next    ;next  ClipRe 

zt 

4   $4 

LONG 

cr_prev    ; previous  CI 

ipRect 

8   $8 

LONG 

cr_lobs 

12   $C 

LONG 

cr_BitMap 

BitMap 

16  $10 

WORD 

cr_MinX 

range 

18  $12 

WORD 

cr_MinY 

20  $14 

WORD 

cr_MaxX 

22  $16 

WORD 

cr_MaxY 

24  $18 

APTR 

cr pi 

28  $1C 

APTR 

cr p2 
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32  $20  LONG    cr_reserved 

3  6  $24  LONG     cr_Flags   ; Flags 

40  $28  LABEL    cr_SIZEOF 

CR_NEEDS_NO_CONCEALED_RASTERS  =  1  ; internal  Flag 
CR_NEEDS_NO_LAYERBLIT_DAMAGE  =  2 

ISLESSX  =  1  ; Flags  for  clipping 
ISLESSY  =  2 
ISGRTRX  =  4 
ISGRTRY  =  8 

LAYERS IMPLE  =  1 

LAYERSMART  =  2 

LAYERSUPER  =  4 

LAYERUPDATING  =  $10 

LAYERBACKDROP  =  $40 

LAYERREFRESH  =  $80 

LAYER_CLIPRECTS_LOST  =  $100 

LMN_REGION  =  -1 

Dec  Hex  STRUCTURE  Layer_Info, 0 

0   $0  APTR    li_top_layer  ;top  Layer 
4   $4  APTR    li_check_lp 
8   $8  APTR    li_obs 

12   $C  STRUCT  li_FreeClipRects,MLH_SIZE 

24  $18  STRUCT  li_Lock, SS_SIZE 

70  $46  STRUCT  li_gs_Head, LH_SIZE 

84  $54  LONG   li_long_reserved 

88  $58  WORD    li_Flags 

90  $5A  BYTE    li_fatten_count 

91  $5B  BYTE    li_LockLayersCount 

92  $5C  WORD    li_LayerInfo_extra_size 
94  $5E  APTR    li_blitbuff 

98  $62  APTR   li_LayerInf o_extra 
102  $66  LABEL   li_SIZEOF 

NEWLAYERINFO_CALLED  =  1 

5.  Draw  Functions 


|  AreaDraw  Define  corner  point  for  AreaFillj 

Call:  error  =  AreaDraw  (    rp,      x,    y) 

dO  -258 (A6)       Al      D0,D1 


LONG        error 
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STRUCT  RastPort  *rp 
SHORT   x,y 

Function:     Inserts  a  point  in  the  vector  list  for  AreaFill. 
Parameters:  rp  RastPort  with  Arealnfo 

x,y  Point  coordinates 

Result :  0  No  error 


lAreaEllipse 


Insert  an  ellipse  for  AreaFill  in  Arealnfo  | 


Call: 


error  =  AreaEllipse(  rp,  ex,  cy,  a,  b) 
dO      -186 (A6)     al  dO  dl  d2  d3 

LONG  error 

STRUCT  RastPort  *rp 

SHORT  cx,cy,a,b 


Function:      Stores  an  ellipse  in  the  vector  buffer. 
Parameters:  rp  RastPort  with  Arealnfo 


cx.cy 

a 

b 


Result: 


Center  of  ellipse 
Horizontal  radius  (a>0) 
Vertical  radius  (b>0) 
No  error 


lAreaEnd  Execute  AreaFill  according  to  vector  table  contents! 


Call: 


Function: 


error  =  AreaEnd(rp) 
dO     -264 (A6)  Al 

LONG  error 

STRUCT  RastPort  *rp 

Processes  the  vector  buffer  of  the  Area  routines  and  fills  the 
calculated  area.  Re-initializes  for  new  AreaMoveQ  calls. 
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Parameters:  rp  RastPort 

Result:           0  No  error 

|AreaMove  Define  starting  point  for  AreaFill| 

Call:  error  =     AreaMove  (   rp,        x,   y) 

dO  -252 (A6)      al        dO   dl 

LONG  error 
STRUCT  RastPort   *rp 

SHORT  x,y 

Function:      Closes  the  last  polygon  and  begins  a  new  one. 

Parameters:  rp  RastPort  with  Arealnfo 

x,y  Position  of  the  starting  point 

Result:          0  No  error 

lUraw  Draw  a  linel 


Call:  Draw(    rp,    x,    y) 

-246 (A6)    al   dO   dl 

STRUCT  RastPort  *rp 
SHORT   x,y        * 

Function:      Draws  a  line  from  the  current  position  to  the  given 
coordinates. 

Parameters:  rp  RastPort 

x,y  Destination  coordinates 

|  DrawEllipse  Uraw  an  ellipse] 

Call:  DrawEllipse (   rp,    ex,    cy,    a,    b   ) 

-180 (A6)  al     dO     dl     d2  d3 

STRUCT  RastPort   *rp 
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SHORT  cx,cy,a,b 
Function:     Draws  an  ellipse  in  RastPort. 

Parameters:  rp  RastPort 

cx,cy  Center  of  ellipse 

a  Horizontal  radius  (a>0) 

b  Vertical  radius  (b>0) 

I  EraseRect  Fi»  a  rectangle  using  the  Back*  ill  hook  | 

Call:  EraseRect  (   rp,   xmin,   ymin,   xmax,   ymax) 

-810 (A6)        al     d0:16   dl:16  d2:16   d3:16 

STRUCT  RastPort  *rp 
SHORT  xmin, ymin, xmax, ymax 

Function:  Fills  a  rectangular  area  in  a  RastPort.  If  the  RastPort  layer  is 
showing,  then  the  BackFill  hook  is  used.  Otherwise,  the 
rectangle  is  deleted. 

Parameters:  rp  RastPort 

xmin,ymin  Upper  left  corner  of  rectangle 

xmax,ymax 

Lower  right  corner  of  rectangle 

iFlood  Fill an  areal 

Call:  error  =  Flood (   rp,   mode,    x,   y) 

dO  -330 (A6)    al  d2        dO  dl 

BOOL        error 
STRUCT  RastPort  rp 
ULONG     mode 
SHORT      x,y 
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Function: 


Fills  an  area  of  any  complexity  with  the  color  or  pattern  set 
in  the  current  draw  mode. 


Parameters: 


Result: 
llnitArea" 


rp 

*.y 

mode 

0 


RastPort  with  TmpRas 
Starting  point  for  fill 

Fill  mode  (0:  through  AOLPen,  1:  only  points 
with  the  color  at  x-y) 

Okay 


Initialize  Arealnfo  vector  matrix 


Call:  lnitArea(  areainfo,  buffer,  maxvectors  ) 

-282 (A6)   aO        al      d0 

STRUCT  Areainfo  *areainfo 
APTR  buffer 
SHORT  maxvectors 

Function:  Initializes  the  vector  table  for  Area  commands.  The  given 
buffer  must  have  at  least  five  bytes  per  vector.  Remember 
that  AreaEllipseO  needs  two  vectors,  and  AreaEnd()  needs 

one. 

Parameters:  areainfo      Areainfo  structure 

buffer  Vector  buffer  (5*maxvectors+5) 

maxvectors 

Maximum  vectors 


|  Move 


Set  coordinates  for  graphics  output | 


Call:  Move(  rp,    x,    y) 

-240 (A6)    al      dO   dl 

STRUCT  RastPort  *rp 
SHORT   x,y 

Function:      Sets  the  coordinates  for  graphics  output  in  the  RastPort. 
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Parameters:  rp 

x,y 
|  Poly  Draw 


RastPort 
Coordinates 


Draw  a  line  according  to  coordinates  in  a  table 


Call:  PolyDraw(  rp,    count   ,   array   ) 

-336 (A6)      al     dO  aO 

STRUCT  RastPort   *rp 
WORD       count 
APTR       array 

Function:  Draws  from  point  to  point  according  to  the  values  in  a 
coordinate  table.  This  function  is  the  same  as  a  Move()  call 
to  the  first  coordinates  followed  by  subsequent  Draw() 
calls. 

Parameters:  rp  RastPort 

count  Number  of  coordinate  points. 

array  Array  with  two  words  per  entry  (x  and  y). 


IReadPixel 


Read  the  color  number  of  a  pixel  | 


Call:  penno  =  ReadPixel  (   rp,   x,   y   ) 

dO  -318 (A6)        al     dO  dl 

LONG       penno 
STRUCT  RastPort   *rp 
SHORT     x,y 

Function:      Gets  the  color  number  of  the  pixel  at  the  given  coordinates 
in  a  RastPort. 


Parameters:  rp 

x,y 


RastPort 
Coordinates 


Result:         Color  number  (0..255)  or  -1  (coordinates  outside  of 
RastPort) 
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I  Read  Pixel  Array8 


Call: 


Read  the  color  numbers  of  a  rectangle  I 


count  =  ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,t<anprp) 
dO  -780(A6)  aO  dOsU     dl:16     d2:16  d3:16  a2         al 


UJNG       count 

STRUCT  RastPort  *rp,*temprp 
UWORD    xstart,ystart,xstop,ystop 
APTR      array 


Function:  ReadPixel()  for  each  point  within  a  rectangular  area  of  a 
RastPort.  The  results  are  written  as  bytes  to  the  given 
buffer. 


Parameters:  rp 


RastPort  structure 


xstart,ystart 


Starting  point  in  RastPort. 


Result:          ] 

Example: 

movea .  I 

l  _Gf xBase, a6 

movea.l  _RastPort,aO 

moveq 

#8,d0 

moveq 

#16, dl 

moveq 

#24, d2 

moveq 

#32, d3 

lea 

_Array,a2 

lea 

_TtapRp,al 

jsr 

_LVOReadPixelArray8 (a6) 

xstop,ystop 

End  point  in  RastPort. 

array  Results  buffer,  at  least 

((((width+15)»4)«4)*(ystop-ystart+l)) 
bytes. 

temprp        Temporary  RastPort  (copy  with  layer=0  and  a 
bit-map   that   can   store   one   row   of  the 

rectangular  area). 

Number  of  pixels  read. 
Read  a  16*16  pixel  area: 
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_Array 
ds.b    16*16 


_TmpRp   .-previously  initialized 


|  Read  PixelLine8  Read  color  numbers  of  a  horizontal  line  | 

Call:  count  =  ReadPixelLine8(rp,xstart,ystart, width, array, temprp) 

dO      -768 (A6)       aO  d0:16  dlsl6  d2    a2    al 

LONG   count 

STRUCT  RastPort  *rp, "temprp 
WORD  xstart,y  start,  width 
APTR   array 

Function:     Like  ReadPixelArray8(),  but  for  only  one  line. 
Parameters:  rp  RastPort 

x,y  Starting  point 

width  Line  width  (in  pixels) 

array  Results  buffer,  at  least  (((width+15)»4)«4) 

bytes. 

temprp        Same  as  with  ReadPixelArray8(). 

I  ReciFill  Fill  a  rectangle  | 

Call:  RectFilK   rp,    xmin,   ymin,    xmax,   ymax) 

-306(A6)      al     d0:16  dl:16  62:16  63:16 

STRUCT  RastPort  *rp 

SHORT  xmin, ymin, xmax, ymax 

Function:     Fills  a  rectangle  in  a  RastPort  with  the  set  color  or  pattern. 

Parameters:  rp  RastPort 
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xmin,ymin  Upper  left  corner  of  rectangle 

xmax.ymax 

Lower  right  corner  of  rectangle 

ISetAPen  Set  color  for  drawing! 

Call:  SetAPen(  rp,   pen   ) 

-342 (A6)    al     dO 

STRUCT  RastPort  *rp 
UBYTE  pen 

Function:      Sets  the  foreground  color  for  graphics  operations. 

Parameters:  rp  RastPort 

pen  Color  number  (0...255) 

ISetBPen  Set  the  background  color | 

Call:  SetBPen(  rp,    pen   ) 

-348 (A6)    al      dO 

STRUCT  RastPort  *rp 
UBYTE  pen 

Function:      Sets  the  second  color  for  graphics  operations. 

Parameters:  rp  RastPort 

pen  Color  number  (0...255) 

|  SetDrMd  Set  draw  mode] 

Call:  SetDrMd  (  rp,    mode   ) 

-354(A6)    al      d0:8 

STRUCT  RastPort  *rp 
UBYTE  mode 
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Function:      Sets  the  draw  mode  for  drawing,  text  output,  and  filling 
areas. 


Parameters:  rp  RastPort 

mode  JAM1 ,  JAM2,  etc. 

Example:       Output  shaded  text: 


**_ 

** 

**_ 

** 

** 

** 

** 

** 

** 

**_ 


Shadow  print 


*  * 

*  * 

*  * 

*  * 

*  * 


Input:   al  =  RastPort 

aO  =  Text 

dO  =  Text  color 

dl  =  Shadow  color 

d2  =  xPos 

d3  =  yPos 


_ShadowPrint 

movem.l  d0-d4/a0-al/a6,  ■ 
movea.l  _Gf xBase, a6 
moveq   #RP_JAM1 , dO 
jsr     _LVOSetDrMd(a6) 


(a7) 


; foreground  color  only 


StrLen 

moveq 

#-l,dO 

sub.  1 

aO.dO 

StrLenLoop 

tst.b 

(a0)  + 

bne.s 

.StrLenLoop 

add.l 

aO.dO 

move . 1 

d0,d4 

move . 1 

4(a7),d0 

addq.w 

#l,d2 

addq.w 

#l,d3 

bsr  .s 

.GiveOut 

move . 1 

(a7),d0 

subq.w 

#l,d2 

subq.w 

#l,d3 

bsr  .s 

.GiveOut 

movent .  1 

(a7 ) +, d0-d4/a0-al/a6 

rts 
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.GiveOut 

movea.l  28(a7),al 
jsr     _LVOSetAPen(a6) 
movea.l  28(a7),al 
move.l   d2,d0 
move .1  d3 , dl 
jsr     _LVOMo ve ( a  6 ) 
movem.l  24(a7),a0-al 
move .1  d4 , dO 
jmp     _LVOText(a6) 


ISetRast 


Fill  an  area  with  a  color  | 


Call:  SetRast  (  rp,    pen   ) 

-234 (A6)    al      dO 

STRUCT  RastPort  *rp 
UBYTE  pen 

Function:      Fills  the  RastPort  with  the  given  color. 

Parameters:  rp  RastPort 

pen  Color  number  (0...255) 

IWritePixel 


Draw  a  pixel | 


Call:  error  =  WritePixel  (   rp,    x,   y) 

dO  -324 (A6)  al     DO  Dl 

LONG        error 
STRUCT  RastPort   *rp 
SHORT     x,y 

Function:      Places  a  pixel  at  the  given  coordinates  in  the  RastPort 
using  the  foreground  color. 


Parameters:  rp 
x,y 
Result:  0 


RastPort 

Pixel  coordinates 

Okay,  -1  coordinates  outside  of  RastPort. 
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fWritePixelArray8  Draw  a  multi-colored  rectangle! 

CO.ll:  count  c  WritePixelArray8(rp,xstart,ystart,xstop,ystop, array, temprp) 

dO  -786IA6)  aO   d0:16      dl:16      d2:16    d3:16    a2  al 

LONG        count 

STRUCT  RastPort  *rp,*temprp 
UWORD  xstart,ystart,xstop,ystop 
APTR   *array 

Function:     Fills  a  rectangle  with  pixels.  The  color  numbers  are  given  in 
a  byte  field. 

Parameters:  See  ReadPixelArray8(). 

Result:  Number  of  pixels  drawn. 

Example :      Write  a  1 6*  1 6  pixel  area: 

movea . 1  _Gf xBase , a6 

movea.l  _RastPort,aO 

moveq   #8,d0 

moveq   #16, dl 

moveq    #24, 62 

moveq   #32, d3 

lea     _Array,a2 

lea     _TmpRp,al 

jsr     _LVOWritePixelArray8(a6) 


.Array 
ds.b    16*16  ;previously  read,  manipulated,  etc. 


_TmpRp   ;already  initialized 

|  WritePixelLine8  Draw  a  multi-colored  horizontal  line| 

Call:  count  =  WritePixelLine8  (rp,xstart,ystart, width, array, temprp) 

dO      -774(A6)        aO  d0:16  dl:16  d2    a2    al 

LONG   count 

STRUCT  RastPort  *rp, * temprp 
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UWORD  xstart,ystart, width 
APTR   array 

Function:     Draws  a  horizontal  line  with  the  color  numbers  given  in  a 
byte  field. 

Parameters:  See  ReadPixelLine8(). 

Result:  Number  of  pixels  drawn. 


Dec  Hex  STRUCTURE  TmpRas , 0 
0   $0  APTR   tr_RasPtr 
4   $4  LONG   tr_Size 
8   $8  LABEL   tr_SIZEOF 


;temporary  raster 
; buffer 
/buffer  size 


RPB_FRST_DOT  =  0, 

RPB_ONE_DOT  =  1, 

RPB_DBUFFER  =  2, 

RPB_AREAOUTLINE  =  3, 

RPB_NOCROSSFILL  =  5, 


RPF_FRST_DOT     = 
RPF_ONE_DOT 
RPF_DBUFFER      = 
RPF_AREAOUTLINE  = 
RPF_NOCROSSFILL  = 


1  ; first  pixel  also 

2  ;pixel  line 

4  ; double  buffering 

8  /outline  mode 

16  ;AreaFill  mode 


RP_JAM1 

=  0  /without  background 

RP_JAM2 

=  1  ;with  background 

RP_COMPLEMENT 

=  2  ; complement 

RP_INVERSVID 

=  4  ; invert 

RPB_TXSCALE  = 

0,  RPFJTXSCALE  =  1 

Dec  Hex 

STRUCTURE  RastPort,0 

0   $0 

LONG 

rp_Layer 

4   $4 

LONG 

rp_BitMap 

8   $8 

LONG 

rp_AreaPtrn 

12   $C 

LONG 

rp_TmpRas 

16  $10 

LONG 

rp_AreaInfo 

20  $14 

LONG 

rp_GelsInfo 

24  $18 

BYTE 

rp_Mask 

25  $19 

BYTE 

rp_FgPen 

26  $1A  BYTE 

rp_BgPen 

27  $1B 

BYTE 

rp_AOLPen 

28  $1C 

BYTE 

rp_DrawMode 

29  $1D 

BYTE 

rp_AreaPtSz 

30  $1E 

BYTE 

rp_linpatcnt 

31  $1F 

BYTE 

rp_Dummy 

32  $20 

WORD 

rp_Flags 

34  $22 

WORD 

rp_LinePtrn 

36  $24 

WORD 

rp_cp_x 
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38 

$26 

WORD 

rp_cp_y 

40 

$28 

STRUCT 

rp_minterms , 8 

48 

$30 

WORD 

rp_PenWidth 

50 

$32 

WORD 

rp_PenHeight 

52 

$34 

LONG 

rp_Font 

56 

$38 

BYTE 

rp_AlgoStyle 

57 

$39 

BYTE 

rp_TxFlags 

58 

$3A 

WORD 

rp_TxHeight 

60 

$3C  WORD 

rp_TxWidth 

62 

$3E 

WORD 

rp_ TxBaseline 

64 

$40 

WORD 

rp_TxSpacing 

66 

$42 

APTR 

rp_RP_User 

70 

$46 

STRUCT 

rp_longreserved, 8 

78 

$4E 

STRUCT 

rp_wordreserved, 1 

92 

$5C 

STRUCT 

rp_reserved,  8 

100 

$64 

LABEL 

rp_SIZEOF 

Dec 

Hex 

STRUCTURE  Arealnfo, 0 

0 

$0 

LONG 

ai_VctrTbl 

4 

$4 

LONG 

ai_VctrPtr 

8 

$8 

LONG 

ai_FlagTbl 

12 

$c 

LONG 

ai_FlagPtr 

16 

$10 

WORD 

ai_Count 

18 

$12 

WORD 

ai_MaxCount 

20 

$14 

WORD 

ai_FirstX 

22 

$16 

WORD 

ai_FirstY 

24 

$18 

LABEL 

ai_SIZEOF 

Example: 


6.  Text  Output 


A  routine  could  calculate  the  color  values  for  an  apple  man 
(fractal,  Mandelbrot  set)  and  store  them  in  byte  arrays, 
which  can  then  be  output  at  the  end  of  a  line  with 
WritePixelLine8(). 


I  Add Font 


Add  a  font  to  the  system  list  | 


Call:  AddFont(  text  Font) 

-480 (A6)  al 

STRUCT  TextFont  *textFont 

Function:      Adds  the  given  font  to  the  system  list. 

Parameters:  textFont     TextFont  structure 
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|  AskFont  Get  the  attributes  of  the  current  font  | 

Call:  AskFont  (rp,    textAttr) 

-474 (A6)    al  aO 

STRUCT  RastPort   *rp 
STRUCT  TextAttr  *textAttr 

Function:     Fills  the  given  TextAttr  structure  with  information  on  the 
RastPort  font. 

Parameters:  rp  RastPort 

textAttr      TextAttr  structure 

lAskSoftStyle  Get  the  current  stylel 

Call:  enable  =  AskSoftStyle(rp) 

dO  -84 (A6)  al 

ULONG  enable 
STRUCT  RastPort   *rp 

Function:     For  the  given  RastPort,  it  returns  the  style  currently  being 
generated  by  the  software. 

Parameters:  rp  RastPort 

Result:  Style  (bit  mask,  undefined  bits  are  set) 

I  Clear  EOL  Delete  the  rest  of  the  line  | 

Call:  ClearEOM  rp   ) 

-42 (A6)        al 

STRUCT  RastPort  *rp 

Function:     Deletes  the  rest  of  a  text  line  starting  from  the  current 
position. 

Parameters:  rp  RastPort 
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|  ClearScreen  Deletes  the  RastPort  from  the  current  position  | 

Call:  ClearScreen  (   rp   ) 

-48 (A6)  al 

STRUCT  RastPort  *rp 

Function:  Deletes  the  rest  of  the  RastPort  starting  from  the  current 
text  position  (ClearEOL(),  then  continue  down  to  the 
bottom  edge). 

Parameters:  rp  RastPort 


ICloseFont  Free  a  font 


Call:  closeFont  ( font ) 

-78 (A6)        al 

STRUCT  TextFont   *font 

Function:      Notifies  the  system  that  the  given  font  is  no  longer  being 
used. 

Parameters:  font  Result  from  OpenFont()/OpenDiskFont() 

|ExtendFont  Create  tf  Extension | 

Call:  success  =  ExtendFont  (font,    fontTags) 

DO  -816 (A6)         AO  Al 

ULONG  success 

STRUCT  TextFont   *font 

STRUCT  Tagltem  *fontTags 

Function:      Assure  that  tfJExtension  is  available. 

Parameters:  font  TextFont  structure 

fontTags     Tagltem  field 

Result:  0  Error 
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|  FontExtent  Get  font  attributes  | 

Call:  FontExtent  (font,    fontExtent) 

-762 (A6)        aO  al 

STRUCT  TextFont    *font 

STRUCT  TextExtent   * fontExtent 

Function:  Fills  the  given  FontExtent  structure  with  information  on 
the  given  font. 

Parameters:  font  TextFont 

fontExtent  FontExtent  structure  to  be  filled. 

I  OpenFont  Open  a  font  | 

Call:  font  =  OpenFont  (textAttr) 

dO  -72 (A6)      aO 

STRUCT  TextFont   *font 
STRUCT  TextAttr   *textAttr 

Function:  Searches  the  GfxLibrary  list  to  find  the  font  that  most 
closely  matches  the  data  given  in  the  TextAttr  structure, 
and  opens  it. 

Parameters:  textAttr      TextAttr  or  XTextAttr  structure 

Result:  TextFont  address  if  a  font  with  the  given  name  was  found, 

or  0.  Warning:  the  attributes  of  the  returned  font  may  not 
exactly  match  the  requested  attributes  (different  height, 
etc.). 


|  RemFont  Remove  a  font  from  the  system  list  I 

Call:  RemFont  (textFont) 

-486 (A6)    al 

STRUCT  TextFont   * textFont 
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Function:  Removes  a  font  from  the  system  list  (as  long  as  it  is  no 
longer  required). 

Parameters:  textFont     TextFont  structure  for  the  font. 

ISetFont  Set  font] 

Call:  SetFont(rp,    font) 

-66 (A6)    al     aO 

STRUCT  RastPort   *rp 
STRUCT  TextFont   *font 

Function:  Sets  the  font  to  be  used  by  a  RastPort.  If  the  font  does  not 
conform  with  the  standards,  then  an  attempt  is  made  to 
convert  it  to  a  usable  format. 

Parameters:  rp  RastPort 

font  Result  from  OpenFont()  or  OpenDiskFont(). 

[  SetSoftSty le  Set  software  style  | 

Call:  newStyle  =  SetSoftStyle(rp,  style,  enable) 

dO         -90 (A6)       al  dO     dl 

ULONG  newStyle , style , enable 
STRUCT  RastPort  *rp 

Function:      Changes  the  software  style  of  the  current  font. 

Parameters:  rp  RastPort 

style  New  values  for  the  bits. 

enable         Bit  mask  with  bits  to  be  changed. 
Result:  Value  with  the  new  style. 
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IStripFont  Remove  tf  Extension  | 

Call:  StripFont  ( font ) 

-822 (A6)      AO 

STRUCT  TextFont  *font 

Function:      Converts  a  2.x  font  into  a  1  .x  font. 

Parameters:  font  TextFont  structure  for  the  font. 

|  Text  Output  a  string  | 

Call:  Text(        rp,    string,    length) 

-60 (A6)    al     aO  dO 

STRUCT  RastPort   *rp 
APTR        string 
WORD       length 

Function:   Outputs  text  to  the  current  position  in  the  RastPort. 

Parameters:  rp  RastPort 

string  Address  of  first  character  of  the  output  string. 

length         Number  of  characters. 

|  TextExtent  Calculate  dimensions  of  a  text  output  | 

Call:  TextExtent (rp,    string,    count,    textExtent) 

-690 (A6)        al     aO  d0:16     a2 

STRUCT  RastPort   *rp 

APTR       string 

WORD       count 

STRUCT  TextExtent   *textExtent 

Function:     Fills  a  TextExtent  structure  with  the  calculated  dimensions 
of  an  output  string. 
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Parameters:  rp 

string 
count 


RastPort 

Address  of  first  character 

Number  of  characters 


Result: 


textExtent  Data  structure  for  result 
Filled  TextExtent  structure 


ITextFit 


Calculate  proper  text  length] 


Call:  chars  =  TextFit(rp,  s,  sL,  tE,  cE,  sD,  cBW,  cBH) 

dO      -696 (A6)  al  aO  dO  a2  a3  dl  d2   d3 

ULONG  chars 

STRUCT  RastPort  *rp 

APTR   s 

OWORD   sL, sD, cBW, cBH 

STRUCT  TextExtent  *tE,cE 

Function:      Checks  how  many  characters  and  returns  a  TextExtent 
structure  of  the  proper  length. 


Parameters:  rp 
s 

sL 
tE 
cE 
sD 


cBW 
cBH 


RastPort 

String 

String  length 

TextExtent  structure  for  the  result. 

Given  TextExtent  structure  of  0. 

Offset  from  one  character  of  the  string  to  the 
next. 

Bit  width  (alternative  to  cE) 

Bit  height  (alternative  to  cE) 
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Result:  Number  of  characters  that  will  fit  in  the  area  (0  is  possible). 

|  TextLength  Length  of  a  text  output  in  a  RastPort  I 

Call:  length  =  TextLength (rp,    string,    count) 

dO  -54 (A6)  al     aO  d0:16 

WORD  length, count 
STRUCT  RastPort  *rp 
APTR        string 

Function:     Returns  the  length  of  a  text  output  in  pixels. 

Parameters:  rp  RastPort 

string  String  address 

count  String  length 

Result:  Text  length  in  pixels. 


WeighTAMatch  Compare  fonts  | 


Call:  weight  =  WeighTAMatch (reqTextAttr,  targetTextAttr,  targetTags) 

dO       -804  (A6)     aO  al  a2 

WORD  weight 

STRUCT  TTextAttr  'reqTextAttr 
STRUCT  TextAttr  'targetTextAttr 
STRUCT  Tagltem  *targetTags 

Function:  Compares  two  TextAttr  structures  and  returns  a  value  that 
describes  how  well  they  match.  The  best  result  is 
MAXFONTMATCHWEIGHT  (perfect  match),  the  worst 
case  is  0.  The  names  are  not  compared. 

Parameters:  reqTextAttr 

Desired  TextAttribute 

targetTextAttr 

Potential  TextAttribute 
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Result: 


targetTags  Extended  attributes  for  targetTextAttr  or  0. 
Match  value  (0...MAXFONTMATCHWEIGHT) 


FS_NORMAL  =  0  ; normal  style 


FSB_UNDERLINED  =  0, 
FSB_BOLD  =  1, 
FSB_ITALIC  =  2, 
FSB_EXTENDED  =  3, 
FSB_COLORFONT  =  6, 
FSB_TAGGED      =  7, 


FSF_UNDERLINED  =  1 
FSF_BOLD  =  2 
FSF_ITALIC  =  4 
FSF_EXTENDED  =  8 
FSF_COLORFONT   =  $40 


; underline 
;bold 
; italics 

; extended 
; colored 


FSF_TAGGED 


=  $80  ;TTextAttr 


FPB_ROMFONT  =  0, 

FPB_DISKFONT  =  1, 

FPB_REVPATH  =  2, 

FPB_TALLDOT  =  3, 

FPB_WIDEDOT  =  4, 

FPB_PROPORTIONAL  =  5, 

FPB_DESIGNED  =  6, 

FPB_REMOVED  =  7, 


FPF_ROMFONT 

FPF_DISKFONT 

FPF_REVPATH 

FPF_TALLDOT 

FPF_WIDEDOT 

FPF_PROPORTIONAL 

FPF_DESIGNED 

FPF_REMOVED 


1 

2 

4 

8 

$10 

$20 

$40 

$80 


;font  from  ROM 

;font  from  disk 

; change  output  direction 

;HiRes  font 

;LoRes  Interlace  font 

.•proportional  font 

/designed  (not  derived) 

;not  available 


Dec  Hex  STRUCTURE  TextAttr,0 

0   $0  APTR    ta_Name   ;font  name 
4   $4  UWORD   ta_YSize  ; height 

6  $6  UBYTE   ta_Style  ; style 

7  $7  UBYTE   ta_Flags  ,-preference  Flags 

8  $8  LABEL   ta_SIZEOF 

Dec  Hex  STRUCTURE  TTextAttr, 0 

0   $0  APTR    tta_Name   ; font  name 
4   $4  UWORD   tta_YSize  ; height 

6  $6  UBYTE   tta_Style  ; style 

7  $7  UBYTE   tta_Flags  ,-preference  Flags 

8  $8  APTR    tta_Tags   ;TagItem  field 


12   $C  LABEL    tta_SIZEOF 


TA_DeviceDPI  =  TAG_USER!1  ;XDPI«16  IYDPI 


MAXFONTMATCHWEIGHT 


32767  .-perfect  match 


Dec  Hex  STRUCTURE  TextFont,MN_SIZE  ,-font 


20  $14  UWORD  tf_YSize 

22  $16  UBYTE  tf_Style 

23  $17  UBYTE  tf_Flags 

24  $18  UWORD  tf_XSize 

26  $1A  UWORD  tf_Baseline 
28  $1C  UWORD  tf_BoldSmear 


,- height 

; style 

; preference  Flags 

/normal  width 

,-base  line 

;bold  value 
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30 

S1E 

UWORD 

tf_Accessors 

32 

$20 

OBYTE 

tf_LoChar 

33 

$21 

UBYTE 

tf_HiChar 

34 

$22 

APTR 

tf_CharData 

38 

$26 

UWORD 

tf_Modulo 

40 

$28 

APTR 

tf_CharLoc 

44 

$2C 

APTR 

t  f_Char Space 

48 

$30 

APTR 

tf_CharKern 

52 

$34 

LABEL 

tf_SIZEOF 

/number  of  users 

; first  character 

; last  character 

; packed  Bit Images 

; bytes  per  line  of  CharData 

; offsets  and  character  widths 

.•proportional  spaces 

; image  offsets 


tf_Extension  =  MN_REPLYPORT 


TE0B_NOREMFONT  =  0,  TE0F_NOREMFONT  =  1  ;not  removable 


Dec 

Hex 

STRUCT 

0 

$0 

UWORD 

2 

$2 

UBYTE 

3 

$3 

UBYTE 

4 

$4 

APTR 

8 

$8 

APTR 

12 

$c 

APTR 

16 

$10 

APTR 

20 

$14 

APTR 

24 

$18 

LABEL 

STRUCTURE  TextFontExtension, 0  ;read  only! 


tfe_MatchWord 

tfe_Flags0 

tfe_Flagsl 

tfe_BackPtr 

tfe_OrigReplyPort 

tfe_Tags 

tfe_OFontPatchS 

tfe_OFontPatchK 

tfe_SIZEOF 


;ID  for  compatibility 
; system  Flags  (TEC.) 

; check  address 

;old  contents  of  tf_Extension 

;TagItem  field 

; private 

/private 


CT_COLORFONT  =  1  ; color  values  are  set 
CT_GREYFONT  =  2  ;grey  scale  only  (dark  to  light) 
CT_ANTIALIAS  =  4  ;AntiAliasing 

CTB_MAPCOLOR  =  0,  CTF_MAPCOLOR  =  1  ;set  rp_FgPen  first 

Dec  Hex  STRUCTURE  ColorFontColors ,  0 
0   $0  UWORD   cfc_Reserved    ;0!! 

2   $2  UWORD   cfc_Count      ; number  of  color  values 
4   $4  APTR    cfc_ColorTable  ; color  table  $xRGB 
8   $8  LABEL   cfc_SIZEOF 


Dec  Hex  STRUCTURE  ColorTextFont 

,tf_SIZEOF 

52  $34  UWORD 

ctf_Flags 

; additional  Flags 

54  $36  UBYTE 

ctf_Depth 

; number  of  BitPlanes 

55  $37  UBYTE 

ctf_FgColor 

; rp_FgPen 

56  $38  UBYTE 

ctf_Low 

; lowest  color 

57  $39  UBYTE 

ctf_High 

.•highest  color 

58  $3A  UBYTE 

ctf_PlanePick 

; ImagePlanes 

59  $3B  UBYTE 

ctf_PlaneOnOff 

;BitMap  mask 

60  $3C  APTR 

ct  f_Color Fontcolor s 

; colors 

64  $40  STRUCT 

ctf_CharData, 8* 

4 

; BitPlanePointer 

96  $60  LABEL 

ctf_SIZEOF 
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Dec  Hex  STRUCTURE  TextExtent, 0 

0   $0  UWORD   te_Width     ;TextLength 
2   $2  UWORD   te_Height    ;tf_YSize 

4   $4  STRUCT  te_Extent>8  ;MinX,MinY,MaxX,MaxY  (relative) 
12   $C  LABEL   te_SIZEOF 


7.  Movable  Objects 
[AddAnimOb 


Add  AnimOb  to  RastPort  list! 


Call:  AddAnimOb  (anOb,    anKey,    rp) 

-156 (A6)      a0  al  a2 

STRUCT  AnimOb  *anOb, **anKey 
STRUCT  RastPort   *rp 

Function:  Adds  an  AnimOb  structure  to  the  given  list  and  initializes 
the  Timer  values  of  the  structure.  Gelslnfo  for  the  RastPort 
must  be  initialized. 


Parameters:  anOb 
anKey 
rp 


AnimOb  structure 

Address  of  the  address  of  the  first  AnimOb. 

RastPort  of  the  AnimOb. 


|AddBob 


Add  a  bob  structure  to  the  GEL  list) 


Call:  AddBob(Bob,   rp) 

-96 (A6)    aO     al 

STRUCT  Bob  *Bob 
STRUCT  RastPort   *rp 

Function:      Adds  the  given  Blitter  object  to  the  RastPort's  list. 

Parameters:  Bob  Blitter  object 

rp  RastPort  of  the  bob 
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|  AddVSprite  Add  a  virtual  sprite  to  the  GEL  list| 

Call:  AddVSprite  (vs,   rp) 

-102 (A6)        aO     al 

STRUCT  VSprite   *vs 
STRUCT  RastPort   *rp 

Function:     Adds  a  VSprite  structure  to  the  RastPort's  list. 

Parameters:  vs  VSprite 

rp  RastPort 

|  Animate  Move  AnimObsl 

Call:  Animate  (anKey,   rp) 

-162 (A6)    aO  al 

STRUCT  AnimOb  **anKey 
STRUCT  RastPort  *rp 

Function:     Animates  all  AminObs  and  their  components. 

Parameters:  anKey        Address  of  the  pointer  to  the  first  AnimOb. 

rp  RastPort  of  the  AnimOb. 

IChangeSprite  Change  a  sprite  | 

Call:  ChangeSprite  (  vp,    s,   newdata) 

-420 (A6)  aO     al  a2 

STRUCT  viewport  *vp 
STRUCT  SimpleSprite  *s 
APTR       newdata 

Function:      Changes  the  appearance  of  a  sprite. 

Parameters:  vp  ViewPort  of  the  sprite  or  0  (=relative  to  start  of 

display). 
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s  Address  of  the  SimpleSprite  structure. 

newdata     Address  (ChipRAM)  of  the  new  hardware 
sprite  data  list. 

1  DoCollision  Check  elements  of  the  GEL  list  for  collisions  | 

Call:  DoCollision  (rp) 

-108 (A6)  al 

STRUCT  RastPort  *rp 

Function:  Checks  every  movable  object  for  border  and  object 
collisions  and  calls  the  GEL  collision  routine  if  one  is 
found. 

Parameters:  rp  RastPort  with  sorted  GEL  list  (see  SortGList()). 

IDrawGList  Display  movable  objects | 

Call:  DrawGList  (rp,  vp) 

-114 (A6)      al     aO 

STRUCT  RastPort  *rp 
STRUCT  Viewport  *vp 

Function:     Calculates  a  new  Copper  list  for  sprites  and  draws  bobs. 

Parameters:  rp  RastPort  of  the  bob. 

v  p  ViewPort  of  the  VSprite. 

|  FreeG  Buffers  Free  the  AminOb  component  buffers  | 

Call:  FreeGBuf  f  ers  (anOb,    rp,   db) 

-600 (A6)  aO  al     dO 

STRUCT  AnimOb  *anOb 
STRUCT  RastPort  *rp 
BOOL       db 
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Function:  Frees  all  buffers  of  all  AnimOb  components  (SaveBuffer, 
Borderline,  CollMask=ImageShadow).  If  desired,  double 
buffering  memory  (DBufPacket,  BufBuffer)  is  also  set  free. 


Parameters:  anOb 
db 


AnimOb 
RastPort 
Flag  for  double  buffering  (TRUE). 


IFreeSprite' 


Free  hardware  sprite] 


Call:  FreeSprite(  pick  ) 

-414 (A6)  dO 

WORD  pick 

Function:     Frees  a  hardware  sprite  for  use  by  other  programs. 
Parameters:  pick  Sprite  number  (0...7) 


I  Getli  Buffers" 


Allocate  all  buffers  for  an  AnimOb  | 


Call:  status  =  GetGBuffers(anOb,   rp,    db) 

dO  -168 (A6)  aO  al     dO 

BOOL  status, db 
STRUCT  AnimOb  *anOb 
STRUCT  RastPort   *rp 

Function:      Attempts  to  allocate  all  memory  for  the  components  of  an 
AnimOb  (SaveBuffer,  BorderLine, 

CollMask=ImageShadow).  Memory  for  double  buffering 
(DBufPacket,  BufBuffer)  is  also  allocated  if  indicated.  If  an 
error  occurs,  memory  already  allocated  is  not  set  free. 


Parameters:  anOb 

rp 
db 


AnimOb  structure 

RastPort  of  the  AnimOb. 

Flag  for  double  buffering  (TRUE). 
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Result: 


0 


Error 


IGetSprite 


Allocate  a  hardware  sprite  | 


Call:  Sprite_Number  =  GetSprite(   sprite,   pick  ) 

dO  -408 (A6)        aO  dO 

SHORT     Sprite_Number,pick 
STRUCT  SimpleSprite  *sprite 

Function:     Attempts  to  allocate  one  of  the  8  hardware  sprites. 

Parameters:  sprite  SimpleSprite  structure  for  the  sprite. 

pick  Sprite  number  (0...7)  or  -1  (any  Sprite). 

Result:  Sprite  number  of  the  allocated  sprite  or  -1  (already  in 

use/none  free). 

llnitGels 


Initialize  GELsl 


Call:  lnitGels(head,  tail,  GInfo) 

-120 (A6)  aO    al    a2 

STRUCT  VSprite  *head,*tail 
STRUCT  Gelslnfo  *GInfo 

Function:     Links  the  VSprite  structures  to  the  GfxBase. 

Parameters:  head  Start  of  list 

tail  End  of  list 

GInfo  Gelslnfo  structure  to  be  initialized. 


llnitGMasks" 


Initialize  AnimOb  mask| 


Call:  initGMasks  (anOb) 

-174 (A6)        aO 

STRUCT  AnimOb  *anOb 
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Function:     Calculate  and  enter  the  mask  values  for  an  AnimOb. 
Parameters:  anOb  AnimOb 

|  InitMasks  Initialize  VSprite  mask  | 

Call:  InitMasks  ( vs ) 

-126 (A6)      aO 

STRUCT  VSprite  *vs 

Function:     Calculates  Borderline  and  CollMask  for  a  VSprite/bob. 

Parameters:  vs  VSprite  structure  of  the  object. 

|  MoveSprite  Move  a  hardware  sprite  | 

Call:  MoveSprite  (   vp,    sprite,    x,   y   ) 

-426 (A6)  aO     al  dO  dl 

STRUCT  Viewport    *vp 

STRUCT  SimpleSprite   *sprite 

SHORT      x,y 

Function:      Positions  a  hardware  sprite  relative  to  the  ViewPort. 

Parameters:  vp  ViewPort  of  the  sprite  or  0  (relative  to  View). 

sprite  SimpleSprite  structure 

x,y  Position  (x-coordinate  +1) 

|  RemlBob  Remove  a  bob  from  the  RastPort  listl 

Call:  RemlBob(bob,    rp,   vp) 

-132 (A6)    aO     al     a2 

STRUCT  Bob  *bob 
STRUCT  RastPort   *rp 
STRUCT  ViewPort   *vp 

Function:     Removes  a  bob  from  the  RastPort's  GEL  list. 
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Parameters:  bob  Blitter  object  to  remove. 

rp  RastPort 

vp  ViewPort  for  raster  synchronization. 

I  RemVSprite  Remove  a  VSprite  from  the  RastPort  list| 

Call:  RemVSprite  (vs) 

-138(A6)         aO 

STRUCT  VSprite  *vs 

Function:     Removes  a  VSprite  from  the  GEL  list  of  the  RastPort. 

Parameters:  vs  VSprite 

ISetCollision  Set  the  collision  routine | 

Call:  SetCollision(num,  routine,  GInfo) 

-144 (A6)     dO   aO       al 

ULONG  num 

APTR   routine 

STRUCT  Gelslnfo  *GInfo 

Function:      Sets  the  collision  routine  for  an  entry. 
Parameters:  num  Number  of  entries 

routine       Collision  routine 

GInfo         Gelslnfo 

|  SortGList  Sort  list  of  movable  objects | 

Call:  SortGList  (rp) 

-150 (A6)      al 

Function:      Sorts  the  objects  list  by  y-x  coordinates. 

Parameters:  rp  RastPort  with  Gelslnfo 

323 


3.  Programming  with  AmigaOS  2.x 


SUSERFLAGS   = 

$O0FF 

VSB_VSPRITE 

=  o. 

VSB_SAVEBACK 

=   1, 

VSB_OVERLAY 

=   2, 

VSB_MUSTDRAW 

=   3, 

VSB_BACKSAVED 

=   8, 

VSB_BOBUPDATE 

=   9, 

VSB_GELGONE 

=  10, 

VSB_VSOVERFLOW  =  11, 

BUSERFLAGS   = 

$00FF 

BB_SAVEBOB 

=  o. 

BB_BOBISCOMP 

=   1, 

BB_BWAITING 

=   8, 

BB_BDRAWN 

=   9, 

BB_BOBSAWAY 

=  10, 

BB_BOBNIX 

=  11, 

BB_SAVEPRESERVE=  12, 

BB_OUTSTEP 

=  13, 

/mask  for  User  VSprite 

VSF_VSPRITE     =  1 

VSF_SAVEBACK    =  2 

VSF_OVERLAY     =  4 

VSF_MUSTDRAW    =  8 

VSF_BACKSAVED   =  $100 

VSF_BOBUPDATE   =  $200 

VSF_GELGONE     =  $400 

VSF_VSOVERFLOW  =  $800 


Flags 

;VSprite,  -BOb 

;save  background 

;mask 

;  draw 

; background 

; update  BOb 

;outside  of  View 

;overf low 


;raask  for  User  BOb  Flags 


BF_SAVEBOB  =     1 

BF_BOBISCOMP  =     2 

BF_BWAITING  =  $100 

BF_BDRAWN  =  $200 

BF_BOBSAWAY  =  $400 

BF_BOBNIX  =  $800 
BF_SAVEPRESERVE=$1000 

BF_OUTSTEP  =$2000 


;do  not  delete 

/AnimOb  component 

;BOb  waiting 

;BOb  drawn 

; remove  BOb 

;BOb  gone 

; background  from  Dbuf 

; clear  Dbuf 


ANFRACSIZE   =     6  /animation  Flags 
ANIMHALF     =  $0020 

RINGTRIGGER  =  $0001 


Dec 

Hex 

STRUCTURE  VS, 0  ;vSprite 

0 

$0 

APTR 

vs_NextVSprite 

;next  structure 

4 

$4 

APTR 

vs_PrevVSprite 

; previous  structure 

8 

$8 

APTR 

vs_DrawPath 

; overlay  vSprite 

12 

$c 

APTR 

vs_ClearPath 

; delete  vSprite 

16 

$10 

WORD 

vs_01dy 

;old  position 

18 

$12 

WORD 

vs_01dx 

20 

$14 

WORD 

vs_VSFlags 

/vSprite  Flags 

22 

$16 

WORD 

vs_Y 

.•position 

24 

$18 

WORD 

vs_X 

26 

$1A  WORD 

vs_Height 

; height 

28 

$1C 

WORD 

vs_Width 

; width  in  Words 

30 

$1E 

WORD 

vs_Depth 

/number  of  BitPlanes 

32 

$20 

WORD 

vs_MeMask 

/collision  mask 

34 

$22 

WORD 

vs_HitMask 

/collision  mask 

36 

$24 

APTR 

vs_ImageData 

/ image 

40 

$28 

APTR 

vs_BorderLine 

/mask  of  all  bits 

44 

$2C 

APTR 

vs_CollMask 

/collision  image 

48 

$30 

APTR 

vs_SprColors 

/Sprite  colors 

52 

$34 

APTR 

vs_VSBob 

,-BOb 

56 

$38 

BYTE 

vs_PlanePick 

/BitPlane  mask  image 

57 

$39 

BYTE 

vs_PlaneOnOf  f 

/same  for  other  planes 

58 

$3A 

LABEL 

vs_SUserExt 

/start  of  user  extension 

58 

$3A 

LABEL 

vs_SIZEOF 
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Dec 

Hex 

STRUCTURE  BOB, 0        ;Blitter  object 

0 

$0 

WORD 

bob_BobFlags     ; Flags 

2 

$2 

APTR 

bob_SaveBuffer   /background  buffer 

6 

$6 

APTR 

bob_ImageShadow  ; Image  mask 

10 

$A 

APTR 

bob_Before      ; previous  Bob 

14 

$E 

APTR 

bob_After        ;next  Bob 

18 

$12 

APTR 

bob_BobVSprite   ;vSprite  structure 

22 

$16 

APTR 

bob_BobComp     ;AnimComp 

26 

$1A 

APTR 

bob_DBuf  f er     ; dBuf Packet 

30 

$1E 

LABEL 

bob_BUserExt 

30 

$1E 

LABEL 

bob_SIZEOF 

Dec 

Hex 

STRUCTURE  AC,0         /AnimComp 

0 

$0 

WORD 

ac_CompFlags     ; Flags 

2 

$2 

WORD 

ac_Timer        /activation  time 

4 

$4 

WORD 

ac_TimeSet      ; start  time 

6 

$6 

APTR 

ac_NextComp     ;next  component 

10 

$A 

APTR 

ac_PrevComp     /previous  component 

14 

$E 

APTR 

ac_NextSeq      /next  sequence 

18 

$12 

APTR 

ac_PrevSeq      /previous  sequence 

22 

$16 

APTR 

ac_AnimCRoutine  /animation  routine 

26 

$1A  WORD 

ac_YTrans       /y 

translation 

28 

$1C 

WORD 

ac_XTrans       /x  translation 

30 

$1E 

APTR 

ac_HeadOb       /AnimOb 

34 

$22 

APTR 

ac_AnimBob      / BOB 

38 

$26 

LABEL 

ac_SIZE 

Dec 

Hex 

STRUCTURE   AO,  0 

AnimOb 

0 

$0 

APTR 

ao_NextOb       , 

next  AnimOb 

4 

$4 

APTR 

ao_PrevOb       , 

previous  AnimOb 

8 

$8 

LONG 

ao_Clock 

number  of  Animate ( ) 

12 

$C 

WORD 

ao_An01dY 

old  position 

14 

$E 

WORD 

ao_An01dX 

16 

$10 

WORD 

ao_AnY 

position 

18 

$12 

WORD 

ao_AnX 

20 

$14 

WORD 

ao_YVel 

velocity 

22 

$16 

WORD 

ao_XVel 

24 

$18 

WORD 

ao_XAccel 

acceleration 

26 

$1A 

WORD 

ao_YAccel 

28 

$1C 

WORD 

ao_RingYTrans 

•ring  translation 

30 

$1E 

WORD 

ao_RingXTrans 

32 

$20 

APTR 

ao_An  imORout  ine 

•animation  routine 

36 

$24 

APTR 

ao_HeadComp 

/AnimComp 

40 

$28 

LABEL 

ao_AUserExt 

40 

$28 

LABEL 

ao_SIZEOF 
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Dec  Hex 

STRUCTURE  DBP, 0 

;dBuf Packet 

0   $0 

WORD 

dbp_BufY 

; screen  position 

2   $2 

WORD 

dbp_BufX 

; 

4  $4 

APTR 

dbp_BufPath 

;vSprite 

8  $8 

APTR 

dbp_Buf Buffer 

; buffer 

12  $C 

APTR 

dbp_BufPlanes 

; background  PlanePointer 

16  $10 

LABEL 

dbp_SIZEOF 

Dec  Hex 

STRUCTURE  GelsInfo.O 

0   $0 

BYTE 

gi_sprRsrvd 

; Sprite  numbers 

1   $1 

BYTE 

gi_Flags 

; Flags 

2   $2 

APTR 

gi_gelHead 

; start  of  list 

6   $6 

APTR 

gi_gelTail 

;end  of  list 

10   $A  APTR 

gi_nextLine 

/Sprite  lines 

14   $E 

APTR 

gi_lastColor 

; color  field 

18  $12 

APTR 

gi_collHandler 

.•collision  routine 

22  $16 

WORD 

gi_leftmost 

24  $18 

WORD 

gi_rightmost 

26  $1A  WORD 

gi_topmost 

28  $1C 

WORD 

gi_bottoinmost 

30  $1E 

APTR 

gi_firstBlissObj 

34  $22 

APTR 

gi_lastBlissObj 

38  $26 

LABEL 

gi_SIZEOF 

Dec  Hex 

STRUCTURE  SimpleSprite 

,0 

0   $0 

APTR 

ss_posctldata 

4  $4 

WORD 

ss_height 

6  $6 

WORD 

ss_x 

8  $8 

WORD 

ss_y 

10   $A  WORD 

ss_num 

12   $C 

LABEL 

ss_SIZEOF 

3.1.9  The  Icon  Library 


The  "icoiUibrary"  is  used  to  process  '.info'  files.  So,  the  base  address  must 
be  given  in  A6  with  the  function  calls. 

Functions  of  the  Icon  Library 

AddFreeList 

BumpRevision 

FindToolType 

FreeDiskObject 

FreeFreeList 

GetDefDiskObject 
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GetDiskObject 

GetDiskObjectNew 

MatchToolValue 

PutDefDiskObject 

PutDiskObject 

Description  of  Functions 
|  AddFreeList  Add  memory  to  FreeList  | 

Call:  status  =  AddFreeList  (free,   mem,    len) 

DO  -72  (A6)  AO  Al        A2 

BOOL        status 
STRUCT  FreeList   *free 
APTR       mem 
ULONG     len 

Function:     Adds  the  given  memory  block  to  a  FreeList. 
Parameters:  free  FreeList 

mem  Memory  address 

len  Size  of  block 

Result:  0  Error 

1  BumpRevision  Create  a  filename  for  a  copy  | 

Call:  result  =  BumpRevision (newbuf,    oldname) 

DO  -108  (A6)  AO  Al 

APTR  result, newbuf .oldname 
Function:     Creates  a  filename  with  "copy_of_"  etc. 
Parameters:  newbuf      New  name  (copy_of_...),  min.  31  bytes 

oldname     Original  filename 
Result:  Address  of  the  new  name  or  0. 
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IFindToolType  Find  the  value  of  a  ToolType  variable | 

Call:  value  =  FindToolType(toolTypeArray,    typeName) 

DO  -96 (A6)  AO  Al 

APTR  value, toolTypeArray, typeName 

Function:      Finds  a  ToolType  field  according  to  the  contents  of  the 
given  variable. 

Parameters:  toolTypeArray 

String  field  (APTRs) 

typeName   Variable  name 

Result:  Address  in  ToolType  string  after  the  typeName  equals  sign 

orO. 

IFreeDiskObject  Free  an  icon's  memory  | 

Call:  FreeDiskObject  (diskobj ) 

-90 (A6)  AO 

STRUCT  Diskobj ect   *diskobj 

Function:     Frees  the  memory   used   by  an  icon   allocated   with 
GetDiskObject(). 

Parameters:  diskobj       DiskObject  structure 


IFreeFreeList  Free  the  FreeList 


Call:  FreeFreeList  (free) 

-54 (A6)  AO 

STRUCT  FreeList   *free 

Function:      Frees  the  memory  entered  in  an  icon's  FreeList,  including 
the  memory  for  the  FreeList  structure. 

Parameters:  free  FreeList 
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I  GetPefPiskObject  Get  default  DiskUb,ject| 

Call:  diskobj  =  GetDefDiskObject  (def_type) 

DO         -120 (A6)  DO 

STRUCT  DiskObj ect  *diskobj 
LONG   def_type 

Function:      Reads  the  default  Workbench  icon  for  an  object  of  the 

given  type. 

Parameters:  def_type     Icon  type 

Result:  DiskObject  or  0 

IGetDiskObject  Get  an  icon  file| 

Call:  diskobj    =  GetDiskObj ect  (name) 

DO  -78 (A6)  A0 

STRUCT  DiskObject   *diskobj 
APTR       name 

Function:      Reads  the  icon  of  the  given  object. 

Parameters:  name  Object  name  or  0  (empty  structure). 

Result:  DiskObject  or  0 

GetPiskObjectNew  Get  a  new  icon  file| 


Call:  diskobj   =  GetDiskObjectNew(name) 

DO  -132 (A6)  A0 

STRUCT  DiskObject   *diskobj 
APTR       name 

Functions,  Parameters,  Results: 

Same  as  GetDiskObject(),  except  that  if  no  ".info"  file  is 
available,  an  attempt  is  made  to  get  the  default  settings  with 
GetDefDiskObjectQ. 
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|  MatchTool  Value  Compare  ToolType  variable  I 

Call:  result  =  MatchToolValue(typeString,   value) 

DO  -102 (A6)  A0  Al 

BOOL     result 

APTR  typeStr ing , value 

Function:      Compares  a  string  with  a  ToolType  variable  value  (may  be 
several  values  separated  with  T). 

Parameters:  typeString  ToolType  values  as  from  FindToolType(). 

value  Comparison  string 

Result:  0  Value  was  not  in  typeString. 

|  PutPefPiskObject  Set  a  Workbench  icon | 

Call:  status  =  PutDefDiskObject  (diskobj  ) 

DO  -126 (A6)  A0 

BOOL        status 

STRUCT  DiskObj ect   *diskobj 

Function:     Changes  the  standard  Workbench  icon  for  the  given 
DiskObject  type. 

Parameters:  diskobj       DiskObject 

Result:  0  Error 

IPutDiskObject  1 


Call:  status  =  PutDiskObj ect  (name,    diskobj) 

DO  -84 (A6)  A0  Al 

BOOL        status 

APTR       name 

STRUCT  DiskObject   *diskobj 

Function:     Writes  an  icon  file  to  disk. 
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Parameters:  name 


Filename 


Result: 


diskobj        DiskObject 
0  Error 


Structures:    See  Workbench  Library. 


3.1.10        The  IFFParse  Library 


The  IFF  file  format  became  an  Amiga  standard  very  quickly.  Today,  all 
sound  and  graphics  programs  use  it.  A  standard  file  format  makes  it 
simple  to  transfer  data  from  one  program  to  another.  The  "iffparsclibrary" 
offers  you  the  easiest  way  to  introduce  this  standard  to  your  own 
programs.  All  functions  are  called  with  the  base  address  in  A6. 


Functions  of  the  IFFParse  Library 


1.  Base  Functions 

AllocIFF 

CloseClipboard 

CloselFF 

FreelFF 

GoodID 

GoodType 

IDtoStr 

InitlFF 

InitTFFasDOS 

InitlFFasClip 

OpenClipboard 

OpenlFF 

ParselFF 

ReadChunkBytes 

ReadChunkRecords 

WriteChunkBytes 

WriteChunkRecords 

2.  Context 

CurrentChunk 
FindCollection 


FindProp 

FindPropContext 

ParentChunk 

PopChunk 

PushChunk 

3.  Handlers 

CollectionChunk 

CollectionChunks 

Entry  Handler 

ExitHandler 

PropChunk 

PropChunks 

StopChunk 

StopChunks 

StopOnExit 

4.  Local  Contextltems 

AllocLocalltem 

FindLocalltem 

FreeLocalltem 
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LocalltemData  StoreltemlnContext 

SetLocalltemPurge  StoreLocalltem 

Description  of  the  Functions 

1.  Base  Functions 

[AiiocIKF  Allocate  an  IFFHandlel 

Call:  iff  =  AllociFF    () 

dO  -30 (A6) 

STRUCT  IFFHandle   *iff 

Function:      Allocates  and  initializes  an  IFFHandle  structure. 

Result:  IFFHandle  or  0 

[CloseClipboard  Close  ClipboardHandlel 

Call:  CloseClipboard    (clip) 

-252 (A6)  aO 

STRUCT  ClipboardHandle   *clip 

Function:     Closes     the     "clipboard. device"     and     frees     the 
ClipboardHandle  structure. 

Parameters:  clip  ClipboardHandle        structure        from 

OpenClipboard(). 

IClosett*  Close  IFFl 

Call:  closeiFF   (iff) 

-48 (A6)        aO 

STRUCT  IFFHandle  *iff 

Function:      Closes  an  IFF  file,  leaving  the  IFFHandle  structure  intact  for 
a  new  OpenIFF()  call. 

Parameters:  iff  IFFHandle  structure  from  OpenIFF(). 


332 


3.1  The  Libraries  and  their  Functions 


IFreelFF  Free  IFFHandlel 


Call:  FreelFF    (iff) 

-54 (A6)      aO 

STRUCT  IFFHandle  *iff 

Function:      Frees  an  IFFHandle  that  was  closed  with  CloseIFF(). 

Parameters:  iff  IFFHandle  structure 

iGoodID  Check  IFF  ID  | 

Call:  isok  =  GoodlD   (id) 

dO  -258 (A6)    dO 

LONG  isok,    id 

Function:     Checks  to  see  if  a  chunk  ID  conforms  with  the  Electronic 
Arts  IFF  85  standard. 

Parameters:  id  32  bit  ChunkID 

Result:  0  ID  not  valid 

I  GoodType  Check  FORM  type] 

Call:  isok  =  GoodType    (type) 

dO  -264 (A6)      dO 

LONG  isok,    type 

Function:     Checks  to  see  if  the  ID  is  a  type  of  FORM  chunk  (EA  IFF 

85). 

Parameters:  type  32  bit  FORMat  chunk  ID 

Result:  0  Not  a  FORM  type 
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lIDtoStr 


Store  ID  as  a  string! 


Call:  str  =  iDtoStr    (id,   buf) 

dO  -270 (A6)    dO     aO 

APTR     str, buf 
LONG     id 

Function:     Writes  the  ID  (longword)  to  the  given  buffer  and  deletes 
the  following  byte. 


Parameters:  id 

buf 
Result:  Buffer 


Longword 
5  byte  buffer 


llnitlFF 


Initialize  IFFHandle  as  UserStream| 


Call:  initlFF    (iff,    flags,    streamhook) 

-228 (A6)    aO        dO  al 

STRUCT  IFFHandle   *iff 

LONG        flags 

STRUCT  Hook     * streamhook 

Function:  Initializes  IFFHandle  with  the  user  routines  for  positioning, 
reading,  and  writing.  The  hook  routines  are  passed  to  the 
Hook,  IFFStreamCmd,  and  IFFHandle  structures  in  registers 

A0-A2. 


Parameters:  iff 
flags 
hook 

llnitlFFasClip 


IFFHandle  structure 

I/O  flags 

Hook  with  stream  routine. 


Call:  initlFFasClip   (iff) 

-240 (A6)  aO 


Initialize  IFFHandle  as  ClipboardStreaml 
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STRUCT  iFFHandle  *iff 

Function:  Initializes  an  IFFHandle  for  the  "clipboarddevice".  Another 
ClipboardHandle  from  OpenClipboard()  must  be  entered  in 
iff_Stream. 

Parameters:  iff  IFFHandle 

InitlFFasDOS  Initialize  IFFHandle  as  DOSStream  | 


Call:  InitlFFasDOS    (iff) 

-234 (A6)  aO 

STRUCT  IFFHandle  *iff 

Function:  Initializes  an  IFFHandle  for  DOS.  Another  FileHandle  from 
Open()  must  be  entered  in  iffJStream  (BPTR). 

Parameters:  iff  IFFHandle  structure 

IQpenClipboard  Get  ClipboardHandle | 

Call:  ch  =  OpenClipboard    (unit) 

dO        -246 (A6)  dO 

STRUCT  ClipboardHandle      *ch 
LONG       unit 

Function:  Opens  the  given  unit  of  the  "clipboard.device"  (normally 
PRIMARY_CLIP)  and  returns  a  structure  for 
InitlFFasClipO. 

Parameters:  unit  "clipboard.device"  unit 

Result:  ClipboardHandle  or  0 

IQpenlFF  Prepare  IFFHandle  for  I/O | 

Call:  error  =  OpenlFF    (iff,    rwmode) 

dO  -36 (A6)      aO        dO 

LONG        error , rwmode 
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STRUCT  IFFHandle  *iff 

Function:  Initializes  an  IFFHandle  structure  for  reading  or  writing 
(IFFF_READ  or  IFFF_WRITE). 

Parameters:  iff  IFFHandle 

rwmode      IFFF_READ  or  IFFF_WRITE 

Result:  Error  code  or  0 

IParselFF  Analyze  IFF] 

Call:  error  =  ParselFF    (iff,    control) 

dO  -42 (A6)        aO        dO 

LONG        error , control 
STRUCT  IFFHandle   *iff 

Function:  Reads  an  IFF  file,  puts  the  chunks  on  the  context  stack, 
and  retrieves  them  in  the  correct  order.  The  corresponding 
chunk  type  handler  is  called. 

Parameters:  iff  IFFHandle  structure 

control       IFFPARSE_SCAN,    IFFPARSE_STEP,    or 
IFFPARSE_RAWSTEP 

Result:  Error  code  or  0 

|  ReadChunkBytes  Read  bytes  of  the  current  chunk  | 

Call:  actual  =  ReadChunkBytes    (iff,    buf,    size) 

dO  -60 (A6)  aO        al       dO 

LONG       actual, size 
STRUCT  IFFHandle  *iff 
APTR       buf 

Function:     Reads  the  given  number  of  bytes  from  IFFHandle  to  the 

buffer. 
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Parameters:  iff 

IFFHandle 

buf 

Read  buffer 

size 

Number  of  bytes 

Result:  Number  of  bytes  read  or  negative  (-error  code). 

1  ReadChunkRecords  Read  structures  of  the  current  chunk  | 

Call:  actual  =  ReadChunkRecords  (iff,  buf,  recsize,  numrec) 

dO       -72  (A6)  aO   al   dO       dl 

LONG   actual, recsize, numrec 
STRUCT  IFFHandle  *iff 
APTR   buf 

Function:     Reads  numrec  structures  of  length  recsize  to  the  buffer. 
Parameters:  iff  IFFHandle 

buf  Read  buffer 

recsize        Size  of  structure 

numrec       Number  of  structures 

Result:  Number  or  negative  (-error  code) 

I  WriteChunkBy tes  Write  to  the  current  chunk  | 

Call:  error  =  WriteChunkBytes    (iff,    buf,    size) 

dO  -66 (A6)  aO        al        dO 

Function:      Writes  size  bytes  to  the  current  chunk. 

Parameters:  iff  IFFHandle 

buf  Write  buffer 

size  Buffer  size 
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Result:  Number  of  written  bytes  or  negative  (-error  code). 

|  WriteChunkRecords  Write  data  structures  to  chunk  | 

COll:  error  =  WriteChunkRecords  (iff,  buf,  recsize,  numrec) 

dO      -78  (A6)  aO   al   dO       dl 

LONG   error, recsize, numrec 
STRUCT  IFFHandle  *iff 
APTR   buf 

Function:     Writes  numrec  structures  of  size  recsize  to  the  current 
chunk. 

Parameters:  iff  IFFHandle 

buf  Buffer 

recsize        Structure  size 

numrec        Number  of  structures 
Result:  Number  or  negative  (-error  code) 


Deo  Hex  STRUCTURE  IFFHandle, 0 
0   $0  ULONG  iff_Stream 
4   $4  ULONG  iff_Flags 
8   $8  LONG   iff_Depth   ; stack  depth 
12   $C  LABEL  iff_SIZEOF  ;not  end  of  structure!!! 

if f_Flags : 

IFFF_READ   =  0  ;read 

IFFF_WRITE  =  1  ; write 

IFFF_FSEEK  =  2  /forward  only 

IFFF_RSEEK  =  4  ;any  direction 

IFFF_RESERVED  =  $FFFF0000  ; important  system  bits 

Dec  Hex  STRUCTURE  ClipboardHandle, iocr_SIZEOF  ;  cbh_Reg 

52  $34  STRUCT  cbh_CBport,MP_SIZE 

86  $56  STRUCT  cbh_SatisfyPort,MP_SIZE 
120  $78  LABEL  cbh_SIZEOF 

IFFERR_EOF        =   -1  ;end  of  file 
IFFERR_EOC        =   -2  ;end  of  context 
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IFFERR_NOSCOPE 

= 

-3 

.•invalid  values  for  PROPs 

IFFERR_NOMEM 

= 

-4 

;no  free  memory 

IFFERR_READ 

= 

-5 

;read  error 

IFFERR_WRITE 

= 

-6 

;write  error 

IFFERR_SEEK 

= 

-7 

;seek  error 

IFFERR_MANGLED 

= 

-8 

/defective  data  in  file 

IFFERR_SYNTAX 

= 

-9 

; IFF  syntax  error 

IFFERR_NOTIFF 

= 

-10 

;not  an  IFF  file 

IFFERR_NOHOOK 

= 

-11 

;no  Hook 

IFF_RETURN2CLIENT 

= 

-12 

; return  to  program 

ID_FORM  =  "FORM' 

ID_LIST  =  "LIST' 

ID_CAT   =  "CAT  * 

ID_PROP  =  'PROP' 

ID_NULL  =  ' 

IFFPARSE_SCAN  =  0 
IFFPARSE_STEP  =  1 
IFFPARSE_RAWSTEP  =  2 


2.  Context 

[CurrentChunk  ContextNode  of  the  current  chunk! 

Call:  top  =  CurrentChunk   (iff) 

dO  -174 (A6)  aO 

STRUCT  ContextNode     *top 
STRUCT  IFFHandle   *iff 

Function:     Returns  the  current  ContextNode  of  the  IFFHandle. 

Parameters:  iff  IFFHandle 

Result:  ContextNode  or  0 

[FindCollection  Get  Collectionltem  list] 

Call:  ci  =  FindCollection  (iff,  type,  id) 

dO   -162 (A6)        aO   dO    dl 

STRUCT  Collectionltem   *ci 
STRUCT  IFFHandle  *iff 
LONG   type ,  id 
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Function:      Gets  the  address  of  a  list  of  Collectionltem  structures  of  the 
given  chunk  type. 


Parameters:  iff 
type 
id 


IFFHandle 

Type 

ID 


Result: 


Address  of  the  last  collection  chunk. 


IFindProp 


Find  StoredProperty  for  a  context | 


Call: 


sp  =  FindProp  (iff,  type,  id) 
dO   -156 (A6)   aO   dO    dl 

STRUCT  StoredProperty  *sp 
STRUCT  IFFHandle  *iff 
LONG   type,  id 


Function:  Finds  the  StoredProperty  structure  set  with  PropChunk()  or 
PropChunks(),  which  was  automatically  created  by 
ParseIFF(). 


Parameters:  iff 
type 
id 


IFFHandle 

FORM  type  (for  example  "ILBM") 

ChunkID  (for  example  "CMAP") 


Result:  StoredProperty  or  0 

IFindPropContext 


Find  ContextNode  of  the  Stored  Property  | 


Call:  en  =  FindPropContext    (iff) 

dO        -168 (A6)  aO 

STRUCT  ContextNode     *cn 
STRUCT  IFFHandle  *iff 


Function:     Retrieves  the  ContextNode,  which  is  contained  as  the 
highest  level  of  the  current  position,  for  example  "FORM". 
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Parameters:  iff  IFFHandle 

Result:  ContextNode 

|  ParentChunk  Get  the  ContextNode  of  the  next  higher  level  I 

Call:  parent  =  ParentChunk   (en) 

dO  -180 (A6)  aO 

STRUCT  ContextNode   *parent,    *cn 

Function:     Gets  the  ContextNode  of  the  next  highest  level,  for 
example  "FORM",  from  the  ContextNode  of  a  chunk. 

Parameters:  en  ContextNode  for  which  parent  node  is  sought. 

Result:  ContextNode  or  0 

|  PopChunk  Get  ContextNode  from  context  stack  | 

Call:  error  =  PopChunk   (iff) 

dO  -90 (A6)        aO 

LONG        error 

STRUCT  IFFHandle  *iff 

Function:     Gets  the  next  context  chunk  from  the  stack  and  frees  all 
Localltems. 

Parameters:  iff  IFFHandle 

Result:  0  or  error  code 

|  PushChunk  Move  ContextNode  to  the  context  stack  | 

Call:  error  =  PushChunk   (iff,    type,    id,    size) 

dO  -84  (A6)  aO        dO  dl     d2 

LONG        error 

STRUCT  IFFHandle  *iff 

LONG   type,  id,  size 
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Function:     Places  a  new  ContextNode  from  DFFStream  on  the  context 
stack. 


Parameters. 

iff 

IFFHandle 

type 

Type  (e.g.  "ILBM") 

id 

ID  (e.g.  "CMAP") 

size 

Chunk  size  or  IFFSIZE_UNKNOWN 

Result: 

0  or  error 

code 

Dec  Hex  STRUCTURE  ContextNode, MLN_SIZE  ;cn_Node 
8   $8  LONG  cn_ID  ;ChunkID 

12   $C  LONG  cnJType  ;FORM  type 

16  $10  LONG  cn_Size  ;Chunk  size 

20  $14  LONG  cn_Scan  ;byte  offset 

24  $18  LABEL  cn_SIZEOF  ;not  end  of  structure!!! 

3.  Handlers 

[CoIlectionChunk  Declare  a  CollectionChunkl 

Call:  error  =  CoIlectionChunk    (iff,    type,    id) 

dO  -138 (A6)  aO        dO  dl 

LONG       error , type , id 
STRUCT  IFFHandle  *iff 

Function:     Declares  a  chunk  to  be  a  collection  chunk  and  installs  a 
handler  that  is  activated  when  the  chunk  is  accessed. 

Parameters:  iff  IFFHandle  (must  not  be  open) 

type  Type  (such  as  "ILBM") 

id  ID  (such  as  "CRNG") 

Result:  0  or  error  code 
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| CollectionChunks  Declare  CollectionChunksl 

Call:  error  =  CollectionChunks    (iff,    list,   n) 

dO  -144 (A6)  aO        al        dO 

LONG       error , n 
STRUCT   IFFHandle   *iff 
APTR       list 

Function:      CollectionChunk()  for  several  chunk  types.  The  list  is  a 
field  of  two  longwords:  type,  ID. 

Parameters:  iff  IFFHandle 

list  Field  with  types  and  IDs 

n  Number  of  list  entries 

Result:  0  or  error  code 

lEntryHandler  Link  handler  to  context | 

Call:  error  =  EntryHandler  (iff,  type,  id,  position,  hook,  object) 

dO      -102 (A6)      aO   dO    dl  d2        al    a2 

LONG   error, type, id, posit ion 
STRUCT  IFFHandle  *iff 
STRUCT  Hook  *hook 
APTR   ob j  ect 

Function:     Installs  hook  for  a  chunk  type.  The  hook  routine  is  called 
for  every  new  chunk  of  the  given  type. 

Parameters:  iff  IFFHandle 

type  Typ  (such  as  "ILBM") 

id  ID(suchas"CMAP") 

position  IFFSLI_... 

hook  Hook  structure  with  handler  routine 
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object         User  data  (hook  routine:  A2) 
Result:  0  or  error  code 

|ExitHandler  Install  chunk  exit  handler! 

Call:  error  =  ExitHandler  (iff,  type,  id,  position,  hook,  object) 

dO      -10B(A6)     aO   dO    dl  d2        al    a2 

Functions,  Parameters,  Results: 

Same  as  EntryHandler(),  except  that  this  routine  is  called 
prior  to  removing  a  chunk. 

IPropChunk  Declare  a  Stored  Property  chunk  | 

Call:  error  =  PropChunk    (iff,    type,    id) 

dO  -114 (A6)        aO        dO  dl 

LONG        error , type , id 
STRUCT  IFFHandle  *iff 

Function:      Installs  a  handler  for  chunks  of  the  given  type. 

Parameters:  iff  IFFHandle  (does  not  have  to  be  open) 

type  Type  (such  as  "ILBM") 

id  ID  (such  as  "CMAP") 

Result:       0  or  error  code 

IPropChunks  Declare  chunks  as  PropChunks| 

Call:  error  =  PropChunks    (iff,    list,    n) 

dO  -120 (A6)  aO        al        dO 

LONG       error.n 
STRUCT  IFFHandle  *iff 
APTR        list 

Function:     PropChunk()  for  several  chunks.  The  list  parameter  is  a  field 
with  two  longwords:  type  and  ID. 
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Parameters:  iff  IFFHandle 

list  List  with  type,  ID 

n  Number  of  chunks 

Result:  0  or  error  code 

I  StopChunk  Declare  StopChunk  I 

Call:  error  =  StopChunk    (iff,    type,    id) 

dO  -126 (A6)        aO        dO  dl 

LONG        error , type , id 
STRUCT  IFFHandle   *iff 

Function:     Declares  a  chunk  to  be  a  StopChunk,  which  stops 
ParseIFF()  when  encountered  (IFFPARSE_SCAN-Modus). 

Parameters:  iff  IFFHandle 

type  Type  (such  as  "ILBM") 

id  ID  (such  as  "BODY") 

Result:  0  or  error  code 

IStopChunks  Declare  StopChunksl 

Call:  error  =  StopChunks    (iff,    list,    n) 

dO  -132 (A6)  aO        al        dO 

LONG        error , n 
STRUCT  IFFHandle  *iff 
APTR        list 

Function:      Several  StopChunk()  calls  (like  PropChunks()  etc.). 
Parameters:  iff  IFFHandle 

list  Field  with  type,  ID 
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n  Number  of  chunks 

Result:  0  or  error  code 

IStopOnExit  Stop  after  chunk] 

Call:  error  =  StopOnExit    (iff,    type,    id) 

dO  -150 (A6)  aO        dO  dl 

LONG       error , type , id 
STRUCT  IFFHandle  *iff 

Function:      Stops  ParseIFF()  in  scan  mode  after  the  given  chunk  is 
processed. 


Parameters:  iff  IFFHandle 

type  Type  (such  as  "BLBM") 

id  ID  (such  as  "BODY") 

Result:  0  or  error  code 


Dec  Hex  STRUCTURE  IFFStreamCmd, 0 

0   $0  LONG   isc_Command  ;IFFCMD_... 
4   $4  APTR   isc_Buf      ;data  buffer 
8   $8  LONG   isc_NBytes   ; number  of  bytes 
12   $C  LABEL  isc_SIZEOF 

Dec  Hex  STRUCTURE  StoredProperty, 0 
0   $0  LONG  spr_Size 
4  $4  APTR  spr_Data 
8   $8  LABEL  spr_SIZEOF 

Dec  Hex  STRUCTURE  Collectionltem, 0 
0   $0  APTR  cit_Next 
4   $4  LONG  cit_Size 
8   $8  APTR  cit_Data 
12   $C  LABEL  cit_SIZEOF 

IFFCMD_INIT  =  0  ; initialization 

IFFCMD_CLEANUP  =  1  ;end 

IFFCMD_READ  =  2  ,-read 

IFFCMD_WRITE  =  3  ; write 
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IFFCMD_SEEK  =  4  ;seek 

IFFCMD_ENTRY  =  5  ;new  Context 

IFFCMD_EXIT  =  6  ;exit  Context 

IFFCMD_PURGELCI  =  7  ; f ree  LocalContextltem 

4.  Local  Contextltems 

[AllocLocalltem  Allocate  a  LocalContextltem  | 

Call:  item  =  AllocLocalltem  (type,  id,  ident,  usize) 

dO     -186 (A6)        dO    dl  d2     d3 

STRUCT  LocalContextltem  *item 
LONG   type,  id,  ident,  usize 

Function:     Allocates  and  initializes  a  LocalContextltem  structure  for 
the  given  amount  of  user  data. 

Parameters:  type,id        Type,  ID 

ident  Contextltem  type 

usize  Size  of  user  data  buffer 

Result:  LocalContextltem  or  0 


FindLocalltem  Get  LocalContextltem  from  the  context  stack  | 


Call:  lei  =  FindLocalltem  (iff,  type,  id,  ident) 

dO    -210  (A6)       aO   dO    dl  d2 

STRUCT  LocalContextltem  *lci 
STRUCT  IFFHandle  *iff 
LONG   type,  id,  ident 

Function:     Searches     the     context     stack     for     the     given 
LocalContextltem. 


Parameters:  iff 

IFFHandle 

type 

Type 

id 

ID 
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ident  Item  type  (such  as  "exhd"  =  ExitHandler) 

Result:  LocalContextltem  or  0 

|  FreeLocalltem  Free  a  LocalContextltem  | 

Call:  FreeLocalltem    (lei) 

-204 (A6)  aO 

STRUCT  LocalContextltem  *lci 

Function:     Frees  the  memory  of  a  LocalContextltem  allocated  with 
AllocLocalItem(). 

Parameters:  lei  LocalContextltem  from  AllocLocalItem(). 

|  LocalltemData  Get  address  of  the  user  data  | 

Call:  data  =  LocalltemData    (lei) 

dO  -192 (A6)  aO 

APTR       data 

STRUCT  LocalContextltem  *lci 

Function:      Returns  the  address  of  the  user  buffer  of  an  LCI. 

Parameters:  lei  LocalContextltem  or  0 

Result:  Data  address  or  0 

|  SetLocalltemPurge  Install  purge  handler  | 

Call:  SetLocalltemPurge    (item,   purgehook) 

-198 (A6)  aO  al 

STRUCT  LocalContextltem  *item 
STRUCT  Hook     *purgehook 

Function:      Installs    a   purge    handler    in    an    LCI    (A0=Hook, 
A1=*IFFCMD_PURGELCI,  A2=LCI). 

Parameters:  item  LocalContextltem 
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purgehook 

Hook  with  purge  routine. 

[StoreltemlnContext  Store  LCI  in  ContextNodel 

Call:  StoreltemlnContext  (iff,  item,  en) 

-222 (A6)  aO   al    a2 

STRUCT  IFFHandle  *iff 

STRUCT  LocalCohtextltem  *item 

STRUCT  ContextNode   *cn 

Function:     Adds  a  LocalContextltem  to  a  ContextNode's  list. 

Parameters:  iff  IFFHandle 

item  LocalContextltem 

en  ContextNode 

|  StoreLocalltem  Store  LCI  on  the  context  stack! 

Call:  error  =  StoreLocalltem   (iff,    item,   position) 

dO  -216 (A6)  aO        al  dO 

LONG  error, position 
STRUCT  IFFHandle  *iff 
STRUCT  LocalContextltem  *item 

Function:     Add  LCI  to  a  ContextNode's  list. 

Parameters:  iff  IFFHandle 

item  LocalContextltem 

position      IFFSLI_ROOT,  EFFSLIJTOP,  or  IFFSLI_PROP 
Result:  0  or  error  code 

Dec  Hex  STRUCTURE  LocalContextltem, MLN_SIZE  ;  lci_Node 
8   $8  ULONG  lci_ID 
12   $C  ULONG  lci_Type 
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16  $10  ULONG  lci_Ident 

20  $14  LABEL  lci_SIZEOF  ;not  end  of  structure!!! 

IFFLCI_PROP         =  'prop' 

IFFLCI_COLLECTION    =  'coll' 

IFFLCI_ENTRYHANDLER  =  'enhd' 

IFFLCI_EXITHANDLER   =  'exhd' 

IFFSLI_ROOT  =  1  ;LCI  in  previously  set  Context 
IFFSLIJTOP  =  2  ;LCI  in  current  Context 
IFFSLI_PROP  =  3  ;LCI  in  FORM  or  LIST 

IFFSIZE_UNKNOWN  =  -1 

3.1.11        The  Intuition  Library 


The  "intuition.library"  handles  global  management  of  the  display  and 
input  from  the  keyboard  and  mouse.  The  base  address  must  be  given  in 
A6. 


Functions  of  the  Intuition  Library 

1.  Screens 

CloseScreen 

CloseWorkBench 

FreeScreenDrawInfo 

GetDefaultPubScreen 

GetScreenData 

GetScreenDrawInfo 

LockPubScreen 

LockPubScreenList 

MakeScreen 

MoveScreen 

NextPubScreen 

OpenScreen 

OpenScreenTagList 

OpenWorkBench 

PubScreenStatus 

QueryOverscan 

RemakeDisplay 

RethinkDisplay 

ScreenToBack 


ScreenToFront 

SetDefaultPubScreen 

SetPubScreenModes 

ShowTitle 

UnlockPubScreen 

UnlockPubScreenList 

ViewAddress 

WBenchToBack 

WBenchToFront 

2.  Windows 

ActivateWindow 

BeginRefresh 

ChangeWindo  wB  ox 

ClearMenuStrip 

ClearPointer 

CloseWindow 

EndRefresh 

ItemAddress 

ModifylDCMP 
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MoveWindow 

MoveWindowInFrontOf 

OffMenu 

OnMenu 

Open  Window 

OpenWindowTagList 

RefreshWindowFrame 

ResetMenuStrip 

SetMenuStrip 

SetMouseQueue 

SetPointer 

SetWindowTitles 

SizeWindow 

ViewPortAddress 

WindowLimits 

WindowToBack 

WindowToFront 

ZipWindow 

3.  Requesters 

AutoRequest 

BuildEasyRequestArgs 

BuildSysRequest 

ClearDMRequest 

DisplayAlert 

EasyRequestArgs 

EndRequest 

FreeSysRequest 

InitRequester 

Request 

SetDMRequest 

SysReqHandler 

4.  Gadgets 

ActivateGadget 

AddGadget 

AddGList 

GadgetMouse 

ModifyProp 

NewModifyProp 


ObtainGIRPort 

OffGadget 

OnGadget 

RefreshGadgets 

RefreshGList 

ReleaseGIRPort 

RemoveGadget 

RemoveGList 

ReportMouse 

SetEditHook 

SetGadgetAttrsA 

5.  Output  Functions 

DisplayBeep 

DrawB  order 

Drawlmage 

DrawImageState 

Eraselmage 

IntuiTextLength 

PrintlText 

6.  Other  Functions 

AddClass 

AllocRemember 

CurrentTime 

DisposeObject 

Doubleclick 

FreeClass 

FreeRemember 

GetAttr 

GetDefPrefs 

GetPrefs 

LocklBase 

MakeClass 

NewObjectA 

NextObject 

Pointlnlmage 

RemoveClass 

SetAttrsA 

SetPrefs 

UnlocklBase 
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Description  of  the  Functions 

1.  Screens 

[CloseScreen  Attempt  to  close  a  screen  | 

Call:  Success  =  CloseScreen  (Screen) 

DO  -66 (A6)  AO 

BOOL        Success 
STRUCT  Screen  *Screen 

Function:  Attempts  to  close  a  screen.  If  successful  and  the  screen  was 
the  last  screen,  then  an  attempt  is  made  to  open  the 
Workbench. 

Parameters:  Screen        Screen  to  be  closed. 

Result:  0  Screen  could  not  be  closed  because  it  still 

contains  windows. 

[Close  WorkBench  Attempt  to  close  Workbench  | 

Call:  Success  =  CloseWorkBench  ( ) 

DO  -78 (A6) 

BOOL  Success 

Function:     Attempts  to  close  the  Workbench. 

Result:  0  Workbench  still  open  because  there  are  still 

windows  from  other  programs  on  screen. 

[FreeScreenDrawInfo  Free  Drawlnfol 

Call:  FreeScreenDrawInf o  (   Screen,    Drlnfo    ) 

-696 (A6)  AO  Al 

STRUCT  Screen  *Screen 
STRUCT  Drawlnfo  *DrInfo 
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Function:  Frees  the  screen's  Drawlnfo  structure  (important  for  future 
operating  system  versions). 

Parameters:  Screen        Screen  with  the  Drawlnfo  structure. 

Drlnfo         Drawlnfo  from  GetScreenDrawInfo(). 

I  GetDefaultPubScreen  Get  default  PublicScreen  | 

Call:  GetDef aultPubScreen  (  Namebuff   ) 

-582 (A6)  AO 

APTR  Namebuff 

Function:     Gets  the  name  of  the  default  PublicScreen. 

Parameters:  Namebuff   Buffer  of  size  MAXPUBSCREENNAME  bytes, 

orO. 

Result:  None.  Will  provide  the  string  "Workbench"  in  Namebuff  if 

there  is  no  current  default  public  screen. 

IGetScreenData  Copy  Screen  structure  | 

Call:  Success  =  GetScreenData (Buffer,  Size,  Type,  Screen  ) 

DO         -426 (A6)       AO       DO     Dl     Al 

BOOL  Success 
STRUCT  Screen  *Screen 
UWORD  Size, Type 
APTR  Buffer 

Function:  With  CUSTOMSCREEN,  copies  the  given  Screen  structure 
to  a  buffer.  If  you  specify  a  different  screen  type,  the  data 
structure  of  the  given  screen  type  is  copied.  This  will  open 
the  Workbench  if  it  was  closed  at  the  time  the  call  was 
made. 

Parameters:  Buffer        Buffer  for  the  Screen  structure. 

Size  Buffer  size 
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Type  Screen  type  (such  as  WBENCHSCREEN) 

Screen  Screen  address  of  a  CUSTOMSCREEN. 

Result:  0  Error  ('Type'  Screen  could  not  be  opened) 

|  GetScreenDrawInf o  Get  Drawlnfo  for  a  screen  | 

Call:  Drlnf o  =  GetScreenDrawInf o  (   Screen  ) 

DO  -690 (A6)  A0 

STRUCT  Drawlnfo   *DrInfo 
STRUCT  Screen  *Screen 

Function:     Gets  a  Drawlnfo  structure  for  the  given  screen. 

Parameters:  Screen        Address  of  a  Screen  structure. 

Result:  Drawlnfo  structure 

ILockPubScreen  Lock  a  PublicScreenl 

Call:  screen  =  LockPubScreen  (  Name   ) 

DO  -510 (A6)  A0 

STRUCT  Screen  * screen 
APTR       Name 

Function:  Prevents  a  PublicScreen  from  being  closed  while  data  is 
being  read.  This  is  needed  to  open  a  window  according  to 
the  screen  dimensions.  If  a  value  of  0  is  given,  the  default 
public  screen  is  addressed  -  usually  the  Workbench  screen. 
If  this  is  closed  at  the  time,  it  is  opened  again 
(OpenWorkBench()). 

Parameters:  Name  Screen  name,  *"Workbench"  or  0 

Result:  Screen  address  or  0 
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ILockPubScreenList  Lock  PublicScreen  list| 

Call:  List  =  LockPubScreenList  ( ) 

DO  -522 (A6) 

STRUCT   List    *List 

Function:  Prevents  the  PublicScreen  list  from  being  changed  and  gets 
a  user  copy  of  this  system  list  (PubScreenNodes). 

Result:  Address  of  the  PublicScreen  list. 

IMakeScreen  MakeVPortQ  for  Intuition  screens  | 

Call:  MakeScreen  (Screen) 

-378 (A6)         AO 

STRUCT  Screen  *Screen 

Function:  Allows  changes  to  the  screen  display  in  a  compatible  way. 
RethinkDisplayO  should  be  called  afterwards. 

Parameters:  Screen        Address  of  the  changed  screen. 

IMoveScreen  Move  screen  | 

Call:  MoveScreen (Screen,   DeltaX,   DeltaY) 

-162 (A6)         AO  DO  Dl 

STRUCT  Screen  *Screen 
WORD       DeltaX,   DeltaY 

Function:  Moves  the  given  screen  according  to  the  given  delta  value. 
Starting  with  AmigaOS2,  the  screen  may  also  be  moved 
horizontally  and  scrolled  up  to  the  left  and  out  of  the 
display  (negative  positions). 

Parameters:  Screen        Screen  to  be  moved. 

DeltaX        Horizontal  interval  in  (screen)  pixels. 

DeltaY        Vertical  interval  in  (screen)  pixels. 
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|  NextPubScreen  Get  name  of  the  next  PublicScreen  | 

Call:  Name  =  NextPubScreen  (   Screen,    NameBuff) 

DO  -534 (A6)  AO  Al 

STRUCT  Screen  *Screen 
APTR       NameBuff,    Name 

Function:     Gets  the  name  of  the  next  PublicScreen. 

Parameters:  Screen        Screen  or  0 

NameBuff  Buffer  consisting  of  MAXPUBSCREENNAME 
bytes. 

Result:  Address  of  buffer  or  0  (not  a  PublicScreen). 

[OpenScreen  Open  screen  | 

Call:  Screen  =  OpenScreen  (NewScreen) 

DO  -198 (A6)         AO 

STRUCT  Screen  *Screen 

STRUCT    (Ext) NewScreen  *NewScreen 

Function:      Opens  a  screen  that's  given  the  definition  of  a  NewScreen 
or  ExtNewScreen  structure. 

Parameters:  NewScreen 

Initialized    NewScreen    or   ExtNewScreen 
structure. 

Tags  (ExtNS): 

Old  function  (see  NS):  SA_Left,  SAJTop,  SA.Width, 
SA_Height,  SA_Depth,  SA_DetailPen,  SA.BlockPen, 
SA_Title,  SA_Font,  SAJType,  SA_BitMap,  SA_ShowTitle, 
SA_Behind,  SA_Quiet. 

SA_DisplayID:      32  bit  display  mode. 

SA_Overscan:       OSCAN_TEXT,  OSCAN_STANDARD, 
OSCAN_MAX  or  OSCAN.VTOEO. 
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SA_DClip:  DisplayClip  region,  see 

QueryOverscan(). 

SA_AutoScroll:  Bool 

For  oversized  screens. 

SA_PubName:       Screen  becomes  a  PublicScreen. 

SA_Pens:  Field  for  DrawInfo.dri_Pens   which 

allows  all  OS  2.0  options. 

SA_PubTask:        Task  that  is  informed  of  the  last  "Visitor" 
window  to  leave  the  PubScreen. 

SA_PubSig:  Signal  bit  for  SA_PubTask. 

SA_Colors:  Colors,  ending  with  -1. 

SA_FullPalette:     Take  over  all  32  Preferences  colors 
(BOOL). 

SA_ErrorCode:      Address  for  error  codes. 

SA_SysFont:         Use  Preferences  font  (0  =  old  font, 
l=Workbench  font) 

Result:  Address  of  the  Screen  structure  or  0  (see  SA_ErrorCode). 

IQpenScreenTagList  Openscreenl 

Call:  Screen  =  OpenScreenTagList  (  NewScreen,  Tagltems  ) 

DO        -612  (A6)  A0  Al 

STRUCT  Screen  *Screen 
STRUCT  NewScreen  *NewScreen 
STRUCT  Tagltem  *TagItems 

Function:  Same  as  OpenScreen()  ExtNewScreen  data  structure,  but 
the  Tagltem  field  is  passed  as  a  parameter  in  place  of  the  old 
ExtNewScreen  method  (test  versions). 
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Functions,  Tags: 

See  OpenScreen() 

Parameters:  NewScreen 

Optional  NewScreen  structure 

Tagltems     Optional  Tagltem  field,  ending  with  TAG_END. 

Result:  Address  of  the  Screen  structure  or  0. 

|  Open  WorkBench  Get  Workbench  address  | 

Call:  WBScreen  =  OpenWorkBench  ( ) 

DO  -210 (A6) 

STRUCT  Screen  *WBScreen 

Function:      Searches  for  the  Workbench  screen  and  tries  to  open  it  if  it 
is  not  already  open. 

Result:  Screen  structure  or  0 

|  PubScreenStatus  Change  status  of  a  PublicScreen  | 

Call:  ResultFlags  =  PubScreenStatus  (  Screen,  StatusFlags  ) 

DO  -552 (A6)         AO      DO 

UWORD  ResultFlags , StatusFlags 
STRUCT  Screen  *Screen 

Function:      Change  status  flags  of  own  PublicScreen. 

Parameters:  Screen        Own  PublicScreen 

StatusFlags 

Current  flags 

Result:  Bit  0  0:  Screen  was  not  public  or  could  not  be  made 

private. 
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IQueryOverscan  (Juery  overscan  area| 

Call:  QueryOverscan (  DisplaylD,   Rect,    OScanType   ) 

-474 (A6)  AO  Al  DO 

ULONG     DisplaylD 
STRUCT  Rectangle   *Rect 
WORD       OScanType 

Function:  Fills  a  Rectangle  structure  with  the  dimensions  of  an 
overscan  type  corresponding  to  the  32  bit  display  mode. 

Parameters:  DisplaylD   32  bit  display  mode 

Rect  Rectangle  structure  to  be  filled. 

OScanType 

OSCAN_... 

Result:  0  MonitorSpec  for  the  ID  does  not  exist. 

|  RemakeDisplay  Recalculate  the  display  | 

Call:  RemakeDisplay  ( ) 

-384 (A6) 

Function:  Complete  recalculation  of  all  screens  (ViewPorts)  and  the 
ViewLord  (Intuition  View).  This  function  should  be 
avoided  (MakeScreen()+RethinkDisplay()  will  usually  do 
the  job). 

IRethinkDisplay  Global  display  reconstructurel 

Call:  RethinkDisplay  ( ) 

-390(A6) 

Function:  Global  reconstruction  of  the  display.  MakeVPort()  should 
be  called  first. 
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|  ScreenToBack  Move  screen  to  the  background  | 

Call:  ScreenToBack  (Screen) 

-246 (A6)  AO 

STRUCT  Screen  *Screen 

Function:     Moves  the  given  screen  to  the  back  of  the  display. 

Parameters:  Screen        Screen  structure 

IScreenToFront  Move  screen  to  the  foreground! 

Call:  ScreenToFront  (Screen) 

-252 (A6)  AO 

STRUCT  Screen  *Screen 

Function:      Moves  the  given  screen  to  the  foreground. 

Parameters:  Screen        Screen  structure 

ISetDefaultPubScreen  Set  standard  PublicScreenl 

Call:  SetDefaultPubScreen(  Name   ) 

-540 (A6)  AO 

APTR  Name 

Function:      Sets  the  default  PublicScreen. 

Parameters:  Name  Name  of  the  PubScreen  or  0  (=Workbench). 

ISetPubScreenModes  Set  global  mode  for  PublicScreenl 

Call:  OldModes  =  SetPubScreenModes  (  Modes   ) 

DO  -546 (A6)  DO 

UWORD  OldModes,   Modes 

Function:      Sets  the  global  mode  for  PublicScreen. 
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Parameters:  Modes        New  flags:  SHANGHAI  -  Workbench  windows 

are  opened  with  the  default  PublicScreen; 
POPPUBSCREEN  -  PublicScreen  moves  to  the 
foreground  when  opened. 

Result:  Old  global  flags. 

IShowTitle  Activate  (or  deactivate)  a  screen's  title  barl 

Call:  ShowTitle (Screen,    Showlt) 

-282 (A6)      AO  DO 

STRUCT  Screen  *Screen 
BOOL       Showlt 

Function:      Manipulates  the  SHOWTITLE  flag  of  a  screen  and 
refreshes  the  display. 

Parameters:  Screen        Screen  structure 

Showlt       Boolean:  TRUE  (title  bar  visible)  or  0 

lUnlockPubScreen  Free  a  PublicScreen! 

Call:  UnlockPubScreen (  Name,    Screen   ) 

-516 (A6)  AO  Al 

APTR       Name 

STRUCT  Screen  *Screen 

Function:     Undo  a  LockPubScreen()  call. 

Parameters:  Name         Name  of  PublicScreen  or  0. 

Screen        Screen  address  if  Name=0. 

lUnlockPubScreenList  Free  PublicScreen  list| 

Call:  unlockPubScreenList  ( ) 

-528 (A6) 

Function:     Undo  a  LockPubScreenList()  call. 
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IViewAddress 


Get  the  address  of  the  ViewLordl 


Call:  ViewLord  =  ViewAddress  ( ) 

DO  -294 (A6) 

STRUCT  View  *ViewLord 

Function:      Gets  the  address  of  the  Intuition  View  structure  ViewLord. 

Result:  View  structure 


WBenchToBack 


Move  Workbench  to  the  background! 


Call:  Success  =  WBenchToBack  ( ) 

DO  -336(A6) 

BOOL  Success 

Function:      Moves  the  Workbench  screen  behind  all  other  screens. 

Result:  0  Workbench  was  not  open. 


IWBenchToFront 


Move  Workbench  to  foreground] 


Call:  Success   =  WBenchToFront  ( ) 

DO  -342 (A6) 

BOOL  Success 

Function:      Move  the  Workbench  screen  in  front  of  all  other  screens. 


Result: 


0 


Workbench  was  not  open. 


Dec  Hex  STRUCTURE  IntuitionBase, 0 
0   $0  STRUCT  ib_LibNode,LIB_SIZE 
34  $22  STRUCT  ib_ViewLord, v_SIZEOF  ; Intuition  View 
52  $34  APTR    ib_ActiveWindow      ,-active  window 
56  $38  APTR   ib_ActiveScreen 
60  $3C  APTR   ib_FirstScreen 
64  $40  ULONG   ib_Flags 
68  $44  WORD   ib_MouseY 
70  $46  WORD   ib_MouseX 
72  $48  ULONG   ib_Seconds  ;time 


; that  window ' s  screen 

; first  screen 

/private 

; INCOMPATIBLE! 
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76   $4C  ULONG      ib_>licros 


DRI_VERSION  =  1 


Dec 

Hex  STRUCT! 

JRE  Drawlnfo, 0 

0 

$0  UWORD 

dri_Version 

•structure  version 

2 

$2  UWORD 

dri_NumPens 

•>=  numDrlPens 

4 

$4  APTR 

dri_Pens 

• PenArray 

8 

$8  APTR 

dri_Font 

; ScreenDef aultFont 

12 

$C  UWORD 

dri_Depth 

; (initial)  BitMap  depth 

14 

$E  UWORD 

dri_ResolutionX 

;l/velocity 

16 

$10  UWORD 

dri_ResolutionY 

' 

18 

$12  ULONG 

dri_Flags 

22 

$16  STRUCT 

dri_longreserved 

,28 

DRIF_NEWLOOK  =  1,  DRIB_NEWLOOK  =  0 


PenArray 

Indices: 

deta 

ilPen 

=  0 
=  1 
=  2 

;old  draw  color 

DlOCiirtsu 

text Pen 

;text  on  background  (0) 

shinePen 

=  3 

;bright  3D  edges 

shadowPen 

=  4 

;dark  3D  edges 

hifi 

UPer 

=  5 

;fill  color  for  current  window 

hifi 

lltextPen 

=  6 

;text  in  current  window  border 

backgroundPen 

=  7 

; background  color  (0) 

hilighttextPen 

=  8 

; highlighted  text 

numDrlPens 

=  9 

Dec 

Hex 

STRUCTURE 

Screen, 0 

0 

$0 

APTR 

sc_ 

.NextScreen   , 

next  screen 

4 

$4 

APTR 

sc. 

.FirstWindow  , 

first  window 

8 

$8 

WORD 

sc_ 

.LeftEdge     , 

position 

10 

$A  WORD 

sc. 

.TopEdge      , 

12 

$c 

WORD 

sc. 

.Width 

size 

14 

$E 

WORD 

sc. 

.Height 

16 

$10 

WORD 

sc. 

.MouseY 

mouse  position 

18 

$12 

WORD 

sc_>touseX 

20 

$14 

WORD 

sc. 

.Flags 

22 

$16 

APTR 

sc. 

.Title 

current  title 

26 

$1A 

APTR 

sc. 

.DefaultTitle 

•title 

30 

$1E 

BYTE 

sc. 

.BarHeight 

•size  of  title  bar 

31 

$1F 

BYTE 

sc. 

.BarVBorder 

32 

$20 

BYTE 

sc. 

.BarHBorder 

33 

$21 

BYTE 

sc_MenuVBorder 

•size  of  menu  bord 

34 

$22 

BYTE 

sc 

_MenuHBorder 

35 

$23 

BYTE 

sc 

_WBorTop 

;size  of  window  bo 

36 

$24 

BYTE 

sc 

_WBorLeft 

363 


3.  Programming  with  AmigaOS  2jc 


37  $25  BYTE    sc_WBorRight 

38  $26  BYTE   sc_WBorBottom 

39  $27  BYTE   sc_KludgeFillOO 

40  $28  APTR   sc_Font 

44   $2C  STRUCT  sc_ViewPort, vp_SIZEOF 
84   $54  STRUCT  sc_RastPort, rp_SIZEOF 
184   $B8  STRUCT  sc_BitMap,bm_SIZEOF 
224   $E0  STRUCT  sc_LayerInfo, li_SIZEOF 
326  $146  APTR   sc_FirstGadget 

330  $14A  BYTE   sc_DetailPen 

331  $14B  BYTE    sc_BlockPen 

332  $14C  WORD   sc_SaveColorO 
334  $14E  APTR   sc_BarLayer 
338  $152  APTR   sc_ExtData 
342  $156  APTR   sc_UserData 
346  $15A  LABEL   sc_SIZEOF 


;font 
/Viewport 
;RastPort 
; BitMap 
; Layer Info 
; gadgets 
;for  gadgets 

; for  Beeping 
; title  Layer 
.•extended  data 

;not  necessarily  end  of  structure! 


SCREENTYPE  =    $F  /mask 

WBENCHSCREEN  =     1  ; Workbench  screen 

PUBLICSCREEN  =     2  ; PublicScreen 

CUSTOMSCREEN  =    $F  ; other  screens 

SHOWTITLE  =    $10  /show  title  bar 

BEEPING  =    $20  /beep  the  screen 

CUSTOMBITMAP  =    $40  /User  BitMap 

SCREENBEHIND  =   $80  /open  screen  behind 

SCREENQUIET  =   $100  /forbid  drawing 

SCREENHIRES  =   $200  /HiRes  gadgets 

NS_EXTENDED  =  $1000  /extended  screen  structure 

AUTOSCROLL  =  $4000  /for  oversized  screens 


STDSCREENHEIGHT  =  -1 
STDSCREENWIDTH   =  -1 


/ NewScreen . Height 
/ NewScreen . Width 


SA_Left 

SA^Top 

SA_Width 

SA_Height 

SA_Depth 

SA_DetailPen 

SA^BlockPen 

SA_Title 

SA_Colors 

SA_ErrorCode 

SA_Font 

SA_SysFont 

SA_Type 

SA_BitMap 

SA_PubName 


TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG. 
TAG_ 


.USER+33 
.USER+34 
USER+35 
.USER+36 
.USER+37 
.USER+38 
.USER+39 
.USER+40 
USER+41 
USER+42 
.USER+43 
.USER+44 
USER+45 
USER+46 
.USER+47 
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SA_PubSig 

= 

TAG_USER+48 

SA_PubTask 

= 

TAG_USER+49 

SA_DisplayID 

= 

TAG_USER+50 

SA_DClip 

= 

TAG_USER+51 

SA_Overscan 

= 

TAG_USER+52 

SA_Obsoletel 

= 

TAG_USER+53 

SA_ShowTitle 

= 

TAG_USER+54 

SA_Behind 

= 

TAG_USER+55 

SA_Quiet 

= 

TAG_USER+56 

SA_AutoScrol 1 

= 

TAG_USER+57 

SA_Pens 

= 

TAG_USER+58 

SA_FullPalette 

= 

TAG_USER+59 

OSERR_NOMONITOR 

0SERR_NOCHIPS 

OSERR_NOMEM 

0SERR_NOCHIPMEM 

OSERR_PUBNOTUNIQUE 

OSERR_UNKNOWNMODE 


=  1  ; monitor  not  available 

=  2  ;old  CustomChips 

=  3  ;  not  enough  memory 

=  4  ;not  enough  ChipMem 

=  5  ;PublicScreen  already  exists 

=  6  ; unknown  display  mode 


Dec  Hex  STRUCTURE  NewScreen , 0 

0  $0  WORD  ns_LeftEdge 

2  $2  WORD  nsJTopEdge 

4  $4  WORD  ns_Width 

6  $6  WORD  ns_Height 

8  $8  WORD  ns_Depth 

10  $A  BYTE  ns_DetailPen 

11  $B  BYTE  ns_BlockPen 

12  $C  WORD  ns_ViewModes 
14  $E  WORD  ns_Type 

16  $10  APTR  ns_Font 

20  $14  APTR  ns_DefaultTitle 

24  $18  APTR  ns_Gadgets 

28  $1C  APTR  ns_CustomBitMap 

32  $20  LABEL  ns_SIZEOF 

STRUCTURE  ExtNewScreen, 

32  $20  APTR  ens_Extension 

36  $24  LABEL  ens_SIZEOF 


position 


preset  color 

display  mode  (old) 

screen  type 

font  TextAttr 

screen  title 

0 

own  BitMap 

ns_SIZEOF 
;TagItem  field 


OSCAN_TEXT 
OSCAN_STANDARD 
OSCAN_MAX 
OSCAN_VIDEO 


=  1  /everything  visible 

=  2  ; right  up  to  the  edge  of  the  screen 

=  3  ; large  as  possible 

=  4  ;more  than  is  possible 


Dec  Hex  STRUCTURE  PubScreenNode,LN_SIZE 
14   $E  APTR   psn_Screen  ; screen 
18  $12  UWORD  psn_Flags   ,-private? 
20  $14  WORD   £sn_Size   ; structure  size+name 
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22  $16  WORD  psn_VisitorCount  ; number  of  VisitorWindows 

24  $18  APTR  psn_SigTask      ; control  task 

28  $1C  UBYTE  psn_SigBit       ; signal  bit 

29  $1D  UBYTE  psn_Padl 

30  $1E  LABEL  psn_SIZEOF 

PSNF_PRIVATE    =  1 

MAXPUBSCREENNAME  =  139  ;max.  name  length 

SHANGHAI       =  1      ; Workbench  window  on  PubScreen 
POPPUBSCREEN   =  2      ; PubScreen  to  front 

2.  Windows 

|  Activate  Window  Activate  a  window  | 

Call:  success  =  Ac  tivateWindow  (Window) 

dO  -450 (A6)  A0 

STRUCT  Window  *Window 

Function:      Activates  a  window  (for  input). 

Parameters:  Window     Window  structure 

Result:  0  Okay 

j  BeginRefresh  Prepare  window  for  a  refresh  | 

Call:  BeginRefresh  (Window) 

-354 (A6)  A0 

STRUCT  Window  *Window 

Function:  The  window's  layer  is  locked  for  other  programs  (such  as 
"input.device"->Intuition()).  During  this  time,  only 
functions  that  don't  handle  other  tasks  may  be  called 
(never  Intuition). 

Parameters:  Window     Window  to  be  refreshed 

Example:      Refresh  several  regions  in  a  window: 
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move.l   im_Class(aO) ,d0         ; IntuiMessage  class 
cmpi.l   #IDCMP_REFRESHWINDOW,dO  ; refresh  window? 
beq     _WindowRefresh 


_WindowRefresh 

movea . 1  im_IDCMPWindow (aO ) , a2 
movea . 1  wd_WScreen ( a2 ) , aO 
lea     sc_LayerInfo(aO) ,a0 
movea .1  aO , a3 
movea. 1  _LayersBase,a6 
jsr     _LVOLockLayerInfo(a6) 


;get  window 

; screen  address 

;get  Layer Info 

;and  save 

; Layers  library 

; lock  access 


movea .1  a2 , aO 

movea . 1  wd_WLayer ( aO ) , aO 

movea. 1  _Regionl,al 

jsr     _LVOInstallClipRegion(a6) 

move .1  dO , d2 

movea. 1  _IntuiBase,a6 

movea. 1  a2,a0 

jsr     _LVOBeginRefresh(a6) 

movea . 1  _IntuiBase , a6 

movea. 1  a2,a0 

moveq   #0,d0 

jsr     _LVOEndRefresh(a6) 


; Window 

; Layer 

; 1 .  Region 

;new  Clipping 

;save  old  Region 

; Intuition 

; Window 

; start  refresh 

; refresh  first  Region 

; Intuition 

; Window 

;NOT  DONE 

;end 


movea. 1  _LayersBase,a6 

movea. 1  a2,a0 

movea . 1  wd_WLay er ( aO ) ,  aO 

movea. 1  _Region2,al 

jsr     _LV0InstallClipRegion(a6) 

movea. 1  _IntuiBase,a6 

movea .1  a2 , aO 

jsr     _LV0BeginRefresh(a6) 

movea. 1  _IntuiBase,a6 

movea. 1  a2,a0 

moveq   #0,d0 

jsr     _LV0EndRefresh(a6) 


;LayersBase 

; Window 

; Layer 

;2nd  Region 

,-new  Clipping 

; Intuition 

; Window 

; start  refresh 

/refresh  second  Region 

; Intuition 

; Window 

•NOT  DONE 

;end 


/refresh  additional  Regions 


movea. 1  _LayersBase,a6 
movea. 1  a2,a0 
movea . 1  wd_WLayer (aO ) , aO 
movea. 1  _RegionN,al 


;LayersBase 
/Window 
/Layer 
/nth  Region 
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jsr     _LV0InstallClipRegion(a6)  ;new  Clipping 

movea.l  _IntuiBase,a6  /Intuition 

movea .1  a2,a0  ; Window 

jsr     _LV0BeginRefresh(a6)  ; start  refresh 

.•refresh  nth  Region 

movea.l  _IntuiBase,a6  /Intuition 

movea.l  a2,a0  ; Window 

moveq   #-l,dO  ;DONE 

jsr     _LV0EndRefresh(a6)  /process  Damagelist 

movea . 1  _LayersBase , a6  ; LayersBase 

movea.l  a2,a0  /Window 

movea.l  wd_WLayer (aO) ,a0  /Layer 

movea.l  d2,al  /old  Region 

jsr     _LV0InstallClipRegion(a6)  /restore  Clipping 

movea.l  a3,a0  /Layer Info 

jsr     _LV0UnlockLayerInfo(a6)  /unlock 


| Change WindowBox  Change  position  and  size  of  a  window! 

Call:  ChangeWindowBox(  Window,  Left,  Top,  Width,  Height) 

-486 (A6)  AO       DO     Dl    D2      D3 

STRUCT  Window  *Window 
WORD  Left, Top, Width, Height 

Function:      Changes  the  position  and  size  of  a  window  simultaneously 
(MoveWindow()  and  SizeWindow()  combined). 

Parameters:  Window     Window  to  be  changed 

Left,  Top,  Width,  Height 

New  position  and  size 

|  ClearMenuStrip  Remove  menus  from  a  windowl 

Call:  ClearMenuStrip  (window) 

-54 (A6)  AO 

STRUCT  Window  *Window 
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Function:  Removes  the  MenuStrip  from  the  given  menu  (waits  if  the 
menu  is  active). 

Parameters:  Window     Window  with  menu 

IClearPointer  Reset  appearance  of  mouse  pointer  | 

Call:  ClearPointer  (Window) 

-60 (A6)  A0 

STRUCT  Window  *Window 

Function:  If  you  have  defined  a  custom  mouse  pointer  for  a  window, 
this  function  will  reset  it  to  the  standard  mouse  pointer. 

Parameters:  Window     Window 

|  CloseWindow  Close  a  window] 

Call:  CloseWindow  (Window) 

-72 (A6)  A0 

STRUCT  Window  *Window 

Function:  Closes  a  window.  If  there  are  messages  in  the  UserPort, 
these  are  also  set  free.  If  there  is  a  MenuStrip,  it  must  first  be 
deleted  with  ClearMenuStrip().  If  it  is  a  "Visitor  Window", 
the  PublicScreen's  counter  is  decremented. 

Parameters:  Window     Window  to  be  closed. 

Example:  Close  a  window  with  a  UserPort  not  created  by  Intuition. 
You  can,  for  example,  assign  one  UserPort  to  10  windows, 
since  the  window  that  is  to  receive  the  IntuitionMessage  is 
visible  from  the  imJDCMPWindow.  When  such  a  window 
is  opened,  a  value  of  0  must  be  given  as  the  IDCMPFlag. 
After  entering  the  common  MsgPort,  the  desired  value  can 
be  set  with  ModifyIDCMP().  Closing  such  a  window  is 
somewhat  more  complicated: 
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movea . 1 

_SysBase,a6 

; ExecBase 

addq . b 

#l,TDNestCnt(a6) 

Multitasking  off 

movea . 1 

_Window, a2 

;get  window 

movea . 1 

wd_UserPort (a2 ) , aO 

;UserPort 

clr.l 

wd_UserPort(a2) 

; delete  entry 

move . 1 

MP_MSGLIST+LH_HEAD (aO ) , d2  ; ListNode 

Loop 

movea . 1 

d2,al 

; message 

move . 1 

(al),d2 

;LN_SUCC 

beq.s 

. StopMsgs 

;LH_TAIL  reached? 

cmpa . 1 

im_IDCMPWindow (al ) , a2 

;Msg  for  this  window? 

bne.s 

.Loop 

;if  not 

move . 1 

al,d3 

;save  Msg 

jsr 

_LVORemove (a6 ) 

; remove  Msg 

movea . 1 

d3,al 

;get  Msg 

jsr 

_LV0ReplyMsg(a6) 

;send  back 

bra.s 

.Loop 

.•continue 

StopMsgs 

movea . 1 

_IntuiBase,a6 

/Intuition 

movea . 1 

a2,a0 

/window 

moveq 

#0,d0 

;no  Flags 

jsr 

_LV0ModifyIDCMP(a6) 

.•prevent  further  Msgs 

movea . 1 

_SysBase,aO 

;Exec 

subq.b 

#l,TDNestCnt(a6) 

.-Multitasking  on 

movea . 1 

a2,a0 

/window 

jsr 

_LVOCloseWindow  ( a6 ) 

; close 

|EndRefresh~ 


End  screen  refresh] 


Call:  EndRefresh (Window,    Complete) 

-366 (A6)         AO  DO 


STRUCT  Window  *Window 
BOOL       Complete 


Function:  Unlocks  a  window  that  was  locked  by  BeginRefresh()  (if 
Complete=TRUE).  If  you  program  a  routine  that  continues 
when  Complete=0,  the  system  may  easily  crash. 

Parameters:  Window     Window 
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Complete    Boolean,  indicates  if  refresh  has  ended. 

|  ItemAddress  Get  address  of  a  Menultem] 

Call:  Item  =  ItemAddress (MenuStrip,   MenuNumber) 

DO  -144 (A6)  AO  DO 

STRUCT  Menultem  *ItemAddress 
STRUCT  Menu  *MenuStrip 
UWORD     MenuNumber 

Function:  Gets  the  Menultem  or  Subltem  belonging  to  the  given 
menu  code. 

Parameters:  MenuStrip  Address  of  the  first  menu  in  a  MenuStrip. 

MenuNumber 

Bit-packed  menu  code 

Result:  Menultem  address  or  0  (MenuNumber  =  MENUNULL) 

IModifylDCMP  Change  IDCMP  flags] 

Call:  success     Modify  IDCMP  (Window,    IDCMPFlags) 

DO  -150  (A6)  AO  DO 

STRUCT  Window  *Window 
ULONG      IDCMPFlags 
BOOL  success 

Function:  Changes  the  status  of  the  IDCMP  (Intuition  Direct 
Communication  Message  Port).  Warning:  the  MsgPort  is 
freed  whenever  the  flags  are  set  to  0  (FreeMem()). 

Parameters:  Window     Window  address 

IDCMPFlags  =  MsgPort  status 

|  Move  Window  Move  a  window] 

Call:  MoveWindow (Window,    DeltaX,   DeltaY) 

-168 (A6)         AO  DO  Dl 
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STRUCT  Window  *Window 
WORD   DeltaX,  DeltaY 

Function:      Moves  a  window  within  a  screen  after  first  checking  the 
coordinates. 

Parameters:  Window     Window  to  be  moved 

DeltaX        Horizontal  delta  value 

DeltaY        Vertical  delta  value 

|  MoveWindowInFrontOf  Change  order  of  windows  1 

Call:  MoveWindowInFrontOf (  Window,    Behindwindow) 

-480 (A6)  A0  Al 

STRUCT  Window  *Window, * Behindwindow 

Function:      Moves  a  window  in  front  of  the  other  windows. 

Parameters:  Window     Window     to     be     placed     in     front     of 

'Behindwindow'. 

BehindWindow 

Window  that  will  end  up  behind  'Window'. 

|  OffMenu  Turn  menu  off  | 

Call:  Of  fMenu  (Window,   MenuNumber) 

-180 (A6)    A0  DO 

STRUCT  Window  *Window 
UWORD     MenuNumber 

Function:      Turn  off  Subltem,  Menultem,  or  an  entire  menu.  Whatever 
is  turned  off  may  not  be  selected. 

Parameters:  Window     Window  with  MenuStrip 

MenuNumber 

Bit-packed  menu  code 
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lOnMenu 


Turn  on  menu,  item,  or  subiteml 


Call:  OnMenu  (Window,    MenuNumber) 

-192 (A6)    AO  DO 

STRUCT  Window  *Window 
UWORD     MenuNumber 

Functions,  Parameters: 

Opposite  of  OffMenu().  Allows  selection  again. 


|  Open  Window 


Open  a  window  | 


Call:  window  =  OpenWindow(NewWindow) 

DO        -204 (A6)    AO 


STRUCT  Window  *Window 
STRUCT  ( Ext ) NewWindow 


*NewWindow 


Function:  Opens  a  window  given  a  NewWindow  or  ExtNewWindow 
structure.  If  WBENCHSCREEN  is  given  as  the  screen  type, 
the  window  is  opened  on  the  Workbench  screen  or  a 
SHANGHAI  screen. 

Parameters:  NewWindow 

NewWindow  or  ExtNewWindow 


Tags: 


New  IDCMP  flags:  IDCMPJDCMPUPDATE 
for  custom  and  BoopsiGadgets; 
IDCMP_CHANGEWINDOW  for  changes  to 
the  window  (position,  size); 
IDCMP_MENUHELP  for  printing  menu  HELP. 

New  type:  PUBLICSCREEN  (preset 
PublicScreen) 

Old  functions  (s.  NW):  WA.Left,  WA_Top,  WA_Width, 
WA_Height,  WAJDetailPen,  WA_BlockPen,  WAJDCMP, 
WA_Flags,  WA_Gadgets,  WA_Checkmark,  WA_Title, 
WA_CustomScreen,  WA_SuperBitMap,  WA_MinWidth, 
WA_MinHeight,  WA_MaxWidth,  WA_MaxHeight. 
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Result: 
Example: 


Bool  tags  for  flags:  WA_SizeGadget,  WA_DragBar, 
WA_DepthGadget,  WA_CloseGadget,  WA_Backdrop, 
WA_ReportMouse. 

WA_ScreenTitle:  screen  tide. 

WA_AutoAdjust:  (BOOL)  adjust  to  screen  dimensions. 

WA_InnerWidth,  WAJtanerHeight:  dimensions  of  the 
region. 

WA_PubScreenName:  name  of  PublicScreens  for  the 
window. 

WA_PubScreen:  Screen  structure  of  the  PublicScreen. 

WA_PubScreenFallBack:  default  PublicScreen  if  the  one 
requested  is  not  available  (BOOL). 

WA_WindowName:  not  yet  implemented. 

WA_Colors:  palette  for  the  window. 

WA_Zoom:  field  with  alternative  size  (ZoomGadget). 

WA_MouseQueue,  WA_RptQueue:  limits  for 
IntuiMessages  of  the  types  IDCMP_MOUSEMOVE  and 
repeated  IDCMP.RAWKEY. 

WA_BackFiU:  LayerHook  for  backfill. 

Window  address  or  0 

Display  AmigaDOS  requesters  in  the  window  entered  in  the 
Process  structure  of  the  currently  running  program.  This  is 
normally  a  Workbench  window.  Programs  that  open  a 
custom  screen  should  change  this  pointer  to  a  window  that 
is  in  the  custom  screen.  Otherwise,  the  Workbench  screen 
will  brought  to  the  foreground  with  every  return  query. 
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jsr     _JjV00penWindow(a6)  ;open  window 

move.l  dO,_Window  ;save  address 

beq     _Zerror  ;in  case  of  error 


movea.l  $4.w,a0  ,-ExecBase 

movea.l  ThisTask(aO) ,a0  /Process  structure 

move.l  pr_WindowPtr (aO) ,_SavedWindowPtr  ;save  old  value 

move.l  dO,pr_WindowPtr(aO)  ; enter  custom  window 

...  ; Program  code 

movea.l  $4.w, aO  ;ExecBase 

movea.l  ThisTask(aO) ,al  ; Process  structure 

movea.l  pr_WindowPtr (al) ,a0  ;our  window 

move.l  _SavedWindowPtr,pr_WindowPtr (al)  ; restore  old  value 

movea.l  _IntuiBase,a6  ; Intuition 

jsr     _LV0CloseWindow(a6)  /close  window 


Proceed  as  follows  to  open  a  window  on  a  PublicScreen: 


LockPubScreen ( )      -  lock  PubScreen 
Get  information  and  modify  window 
OpenWindowO        -  open  window 
UnlockPubScreen ( )    -  free  PublicScreen 


CloseWindowO       -  close  window 

IQpenWindowTagList  Open  window  | 

Call:  Window  =  OpenWindowTagList  (  NewWindow,  Tagltems) 

DO       -606 (A6)  AO         Al 

STRUCT  Window  *Window 
STRUCT  NewWindow  *NewWindow 
STRUCT  Tagltem  *TagItems 

Function:     Like  OpenWindow()  with  ExtNewWindow,  except  the 
Tagltem  field  is  passed  as  a  parameter. 

Parameters:  NewWindow 

Optional  NewWindow  structure 
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Tagltems     Optional  Tagltem  field 

Result:  Window  address  or  0 

|  Refresh WindowFrame  Refresh  the  window  frame] 

Call:  Ref  reshWindowFrame  (Window) 

-456 (A6)  AO 

STRUCT  Window  *Window 

Function:      Refreshes  the  window  frame  of  the  given  window. 

Parameters:  Window     Window 

|  ResetMenuStr  ip  Super-fast  SetM  enuStripQ  | 

Call:  Success  =  ResetMenuStrip (window,   Menu) 

DO  -702  (A6)  AO  Al 

BOOL       Success 
STRUCT  Window  *Window 
STRUCT  Menu   *Menu 

Function:  If  a  MenuStrip  has  been  removed  from  a  window  and  not 
changed  in  the  meantime,  it  can  be  activated  again  with  this 
function  without  having  to  recalculate  JazzX,  JazzY, 
BeatX,  and  BeatY. 

Parameters:  Window     Window 

Menu         First  menu  of  the  MenuStrip. 

Result:  TRUE 

Example:      Turn  off  MenuStrip  while  a  program  is  executing: 

movea.l  _IntuiBase,a6  ;must  happen  first 

movea . 1  _Window, aO 

lea     _MenuStrip,al 

jsr     _LVOSetMenuStrip(a6) 
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; jumps  to  '_Routine'  possible  from  here 

movea.l  _IntuiBase,a6  ; Intuition 

movea.l  _Window,aO  ; window 

jsr     _LV0ClearMenuStrip(a6)  ;turn  off  menu 


_Routine 
...  ;save  registers,  etc. 

movea.l  _IntuiBase,a6  ; Intuition 

movea.l  _Window,aO  ; window 

jsr     _LV0ClearMenuStrip(a6)  ;turn  off  menu 

;now  Flags  such  as 

; CHECKED  or  ITEMENABLED  can  be  changed 

; Routine 

movea.l  _IntuiBase,a6  ,-Intuition 

movea.l  _Window,aO  ; window 

lea  _MenuStrip,al  ;old  menu 

jsr  _LV0ResetMenuStrip(a6)  ;reactivate 

...  (restore  registers,  etc. 


rts 


|  SetMenuStrip  Set  MenuStrip  in  a  window  | 

Call:  Success  =  SetMenuStrip  (Window,    Menu) 

DO  -264 (A6)  AO  Al 

BOOL        Success 
STRUCT  Window  *Window 
STRUCT  Menu  *Menu 

Function:      Installs  a  MenuStrip  in  a  window  and  calculates  the  menu 
boxes  (JazzX/.Y,  BeatX/.Y). 

Parameters:  Window     Window 

Menu         First  Menu  structure 

Result:  TRUE 
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SetMouseQueue 

Set  maximum  number  of  mouse  movement  messages 


Call:  old  =  SetMouseQueue  (  Window,   QueueLength  ) 

DO  -498 (A6)  AO  DO 

STRUCT  Window  *Window 
UWORD     QueueLength 
LONG         Old 

Function:  Sets  the  maximum  number  of  mouse  movement  messages 
that  may  lie  unanswered  in  the  window's  MessagePort 
(only  meaningful  with  slow  languages  such  as  C,  BASIC, 
etc.). 

Parameters:  Window     Window 

QueueLength 

Number  of  MouseMove  messages. 

Result:  Old  queue  length  or  -1  (unknown  window). 

|  SetPointer  Set  the  mouse  pointer  1 

Call:  SetPointer  (Window,  Pointer,  Height,  Width,  XOffset,  YOffset) 

-270 (A6)    AO      Al       DO      Dl      D2       D3 

STRUCT  Window  'Window 

APTR   Pointer 

WORD   Height,  Width,  XOffset,  YOffset 

Function:      Sets  the  mouse  pointer  for  a  window. 
Parameters:  Window     Window 

Pointer       Sprite  data 

Height        Sprite  height 

Width         Width  (1...16) 
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XOffset,  YOff set 

Offset  from  selection  point. 

|  Set  Window  litles  Set  title  bar  text  | 

Call:  SetWindowTitles  (Window,  WindowTitle,  ScreenTitle) 

-276 (A6)        AO      Al  A2 

STRUCT  Window  *Window 

APTR   WindowTitle, ScreenTitle 

Function:  Defines  the  text  displayed  in  the  title  bar  of  the  active 
window  and  screen. 

Parameters:  Window     Window 

WindowTitle 

Window  tide,  0  (empty),  or  -1  (do  not  change) 

ScreenTitle 

Screen  title,  0  (empty)  or  -1  (do  not  change) 

|  SizeWindow  Change  window  size| 

Call:  SizeWindow  (Window,    DeltaX,    DeltaY) 

-288 (A6)         AO  DO  Dl 

STRUCT  Window  *Window 
WORD       DeltaX,   DeltaY 

Function:  Change  the  size  of  a  window  (only  within  the  limits  of 
MinWidth-MinHeight,  MaxWidth-MaxHeight,  and  if  the 
window  has  a  Size  gadget). 

Parameters:  Window     Window 

DeltaX        Delta  value  for  width 

DeltaY        Delta  value  for  height 
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IViewPortAddress  Get  a  ViewPortl 

Call:  viewport  =  viewport  Address  (Window) 

DO  -300 (A6)  A0 

STRUCT  Window  *Window 
STRUCT  Viewport   *ViewPort 

Function:      Returns  the  address  of  the  ViewPort  containing  the  given 
window. 

Parameters:  Window     Window 

Result:  Screen  ViewPort  of  the  window. 

|  WindowLimits  Define  limits  for  window  size  | 

Call:  Success  -  WindowLimits  (Window,    MinWidth,   HinHeight,   MaxWidth,    MaxHeight) 

DO  -318  (A6)  A0  DO  Dl  D2  D3 

BOOL       Success 
STRUCT  Window  *Window 
WORD       MinWidth,   MinHeight 
UWORD     MaxWidth,   MaxHeight 

Function:      Sets  minimum  and  maximum  values  for  window  size. 

Parameters:  Window     Window 

MinWidth,  MinHeight,  MaxWidth,  MaxHeight 

New  size  limits,  0  (do  not  change)  or  -1  (full 
screen) 

Result:  0  Error 

|  WindowToBack  Move  window  behind  all  other  windows  | 

Call:  WindowToBack  (Window) 

-306 (A6)  A0 

STRUCT  Window  *Window 
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Function:     Moves  a  window  to  the  back. 
Parameters:  Window     Window 


IWindowToFront 


Moves  a  window  in  front  of  all  others! 


Call:  WindowToFront  (Window) 

-312 (A6)  AO 

STRUCT  Window  *Window 

Function:      Move  window  to  the  front. 

Parameters:  Window     Window 


|  Zip  Window 


Activate  alternative  window  size  and  position  | 


Call:  ZipWindow(  Window) 

-504 (A6)    AO 

STRUCT  Window  *Window 

Function:     Like  ZoomGadget:  the  window  is  moved  to  the  alternative 
position  with  the  alternative  size. 

Parameters:  Window     Window 


Dec 

Hex  STRUCTURE  Window, 0 

0 

$0  APTR 

wd_Next Wi  ndow 

next  window 

4 

$4  WORD 

wd_LeftEdge 

position 

6 

$6  WORD 

wd_TopEdge 

8 

$8  WORD 

wd_Width 

size 

10 

$A  WORD 

wd_Height 

12 

$C  WORD 

wd_MouseY 

relative  mouse  positi 

14 

$E  WORD 

wd_MouseX 

16 

$10  WORD 

wd_MinWidth 

minimum  size 

18 

$12  WORD 

wd_MinHeight 

20 

$14  WORD 

wd_MaxWidth 

maximum  size 

22 

$16  WORD 

wd_MaxHe  ight 

24 

$18  LONG 

wd_Flags 

Flags  see  below 

28 

$1C  APTR 

wd_MenuStrip 

first  menu 

32 

$20  APTR 

wd_Title 

title  string 

36 

$24  APTR 

wd_FirstRequest 

active  Requester 

40 

$28  APTR 

wd_DMRequest 

double-menu  Requester 
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44  $2C 

WORD 

wd_ReqCount      ; 

number  of  Requesters 

46  $2E 

APTR 

wd_WScreen      ; 

Screen 

50  $32 

APTR 

wd_RPort        ; 

RastPort 

54  $36 

BYTE 

wd_BorderLeft    , 

border  size 

55  $37 

BYTE 

wd_BorderTop    , 

56  $38 

BYTE 

wd_BorderRight   , 

57  $39 

BYTE 

wd_BorderBottom  , 

58  $3A  APTR 

wd_BorderRPort   , 

border  RastPort 

62  $3E 

APTR 

wd_FirstGadget 

first  Gadget 

66  $42 

APTR 

wd_Parent 

window  (activation) 

70  $46 

APTR 

wd_De  s  c  endant 

74  $4A 

APTR 

wd_Pointer 

mouse  data 

78  $4E 

BYTE 

wd_PtrHeight 

79  $4F 

BYTE 

wd_PtrWidth 

80  $50 

BYTE 

wd_XOffset 

81  $51 

BYTE 

wd_YOffset 

82  $52 

ULONG 

wd_IDCMPFlags 

IDCMP  Flags 

86  $56 

APTR 

wd_UserPort 

IDCMP 

90  $5A 

APTR 

wd_WindowPort 

ReplyPort  (Intuition) 

94  $5E 

APTR 

wd_MessageKey 

Msg 

98  $62 

BYTE 

wd_DetailPen 

no  longer  meaningful 

99  $63 

BYTE 

wd_BlockPen 

100  $64 

APTR 

wd_CheckMark 

Image  with  new  check  mark 

104  $68 

APTR 

wd_ScreenTit le 

•screen  title 

108  $6C 

WORD 

wd_GZZMouseX 

mouse  position  within  screen 

110  $6E  WORD 

wd_GZZMouseY 

112  $70 

WORD 

wd_GZZWidth 

■size  of  region 

114  $72 

WORD 

wd_GZZHeight 

116  $74 

APTR 

wd_ExtData 

•extension  structure 

120  $78 

APTR 

wd_UserData 

•NOT  available 

124  $7C 

APTR 

wd_WLayer 

•Layer 

128  $80 

APTR 

wd_IFont 

•Text  Font 

132  $84 

ULONG 

wd_MoreFlags 

•new  system  Flags 

136  $88 

LABEL 

wd_Size 

•size  definition 

136  $88 

LABEL 

wd_SIZEOF 

;not  necessarily  end  of  structure! 

WINDOWSIZING 

=         1  ;Siz 

a  gadget  available 

WINDOWDRAG 

=         2  ;mov< 

ible  window 

WINDOWDEPTH 

=         4  ;win< 

3ow  overlapping  gadget 

WINDOWCLOSE 

=         8  ;clo 

se  gadget 

SIZEBRIGHT 

=       $10  ;Siz 

5  gadget  on  the  right 

SIZEBBOTTOM 

$20  ;bot 

com  Size  gadget 

REFRESHBITS 

=       $C0  ;ref- 

resh  type 

SMART_REFRESH 

=         0  ; inc 

cemental  save 

SIMPLE_REFRESH 

=       $40  ;maro 

jal  refresh 

SUPER_BITMAP 

=       $80  ;buf 

:er  everything 

OTHER_REFRESH 

$C0  ;oth< 

sr  methods 

BACKDROP 

$100  ;bacl 

tground  window 
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REPORTMOUSE  =  $200  ; report  mouse  movements 

GIMMEZEROZERO  =  $400  ,-window  with  border 

BORDERLESS  =  $800  ,-window  without  border 

ACTIVATE  =  $1000  ,-activate  upon  opening 

WINDOWACTIVE  =  $2000  /currently  active  window 

INREQUEST  =  $4000  ,-Requesters  available 

MENUSTATE  =  $8000  ,-menus  displayed 

RMBTRAP  =  $10000  ;no  menu  with  right  mouse  button 

NOCAREREFRESH  =  $20000  ;no  refresh  messages 

NW_EXTENDED  =  $40000  ,-extended  NewWindow  structure 

WINDOWREFRESH  =  $1000000  ,-window  being  refreshed 

WBENCHWINDOW  =  $2000000  ; Workbench  window 

WINDOWTICKED  =  $4000000  ,-window  received  time  impulse 

VISITOR  =  $8000000  ,-Visitor  window 

ZOOMED  =  $10000000  ; zoomed  window 

HASZOOM  =  $20000000  ,-window  with  Zoom  gadget 

SUPER_UNUSED  =  $C0F80000  ; unused  bits 


DEFAULTMOUSEQUEUE 


=  5 


,- number  of  unanswered  Msgs 


Dec  Hex 

STRUCTURE  NewWindow, 0 

0   $0 

WORD 

nw_LeftEdge 

position 

2   $2 

WORD 

nw_TopEdge 

4   $4 

WORD 

nw_Width 

size 

6   $6 

WORD 

nw_Height 

8   $8 

BYTE 

nw_Detai 1 Pen 

meaningless 

9   $9 

BYTE 

nw_BlockPen 

10   $A 

LONG 

nw_IDCMPFlags 

IDCMP  Flags 

14   $E 

LONG 

nw_Flags 

Flags  (see  window) 

18  $12 

APTR 

nw_FirstGadget 

Gadgets 

22  $16 

APTR 

nw_CheckMark 

menu  check  mark 

25  $1A  APTR 

nw_Title 

title 

30  $1E  APTR 

nw_Screen 

screen 

34  $22 

APTR 

nw_BitMap 

SuperBitMap 

38  $26 

WORD 

nw_MinWidth 

min.  size 

40  $28 

WORD 

nw_MinHeight 

42  $2A  WORD 

nw_MaxWidth 

max.  size 

44  $2C 

WORD 

nw_MaxHeight 

46  $2E  WORD 

nw_Type 

screen  type 

48  $30 

LABEL 

nw_SIZE 

48  $30 

LABEL 

nw_SIZEOF 

STRUCTURE  ExtNewWindow 

nw_SIZE 

48  $30 

APTR 

enw_Extension 

Tagltem  field 

52  $34 

LABEL 

enw_SIZEOF 

Tags: 

WA_Left 

=  TAG_USEI 

*  +  100 

WA_Top 

=  TAG_USE1 

*  +  101 
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WA_Width 

= 

TAG_USER 

+ 

102 

WA_Height 

= 

TAG_USER 

+ 

103 

WA_DetailPen 

= 

TAG_USER 

+ 

104 

WA_BlockPen 

= 

TAG_USER 

+ 

105 

WA_IDCMP 

= 

TAG_USER 

+ 

106 

WA_Flags 

= 

TAG_USER 

+ 

107 

WA_Gadgets 

= 

TAG_USER 

+ 

108 

WA_Checkmark 

= 

TAG_USER 

+ 

109 

WA_Title 

= 

TAG_USER 

+ 

110 

WA_ScreenTitle 

= 

TAG_USER 

+ 

111 

WA_CustomScreen 

= 

TAG_USER 

+ 

112 

WA_Supe  r  B  i  tMap 

= 

TAG_USER 

+ 

113 

WA_MinWidth 

= 

TAG_USER 

+ 

114 

WA_MinHeight 

= 

TAG_USER 

+ 

115 

WA_MaxWidth 

= 

TAG_USER 

+ 

116 

WA_MaxHeight 

= 

TAG_USER 

+ 

117 

WA_InnerWidth 

= 

TAG_USER 

+ 

118 

WA_InnerHeight 

= 

TAG_USER 

+ 

119 

WA_PubScreenName 

= 

TAG_USER 

+ 

120 

WA_PubScreen 

= 

TAG_USER 

+ 

121 

WA_PubScreenFallBack 

= 

TAG_USER 

+ 

122 

WA_WindowName 

= 

TAG_USER 

+ 

123 

WA_Colors 

= 

TAG_USER 

+ 

124 

WA_Zoom 

= 

TAG_USER 

+ 

125 

WA_MouseQueue 

= 

TAGJUSER 

+ 

126 

WA_BackFill 

= 

TAG_USER 

+ 

127 

WA_RptQueue 

= 

TAG_USER 

+ 

128 

WA_SizeGadget 

= 

TAG_USER 

+ 

129 

WA_DragBar 

= 

TAG_USER 

+ 

130 

WA_DepthGadget 

= 

TAG_USER 

+ 

131 

WA_CloseGadget 

= 

TAG_USER 

+ 

132 

WA_Backdrop 

= 

TAG_USER 

+ 

133 

WA_ReportMouse 

= 

TAG_USER 

+ 

134 

WA_NoCareRe fresh 

= 

TAG_USER 

+ 

135 

WA_Borderless 

= 

TAG_USER 

+ 

136 

WA_Activate 

= 

TAG_USER 

+ 

137 

WA_RMBTrap 

= 

TAG_USER 

+ 

138 

WA_WBenchWindow 

= 

TAG_USER 

+ 

139 

WA_SimpleRefresh 

= 

TAG_USER 

+ 

140 

WA_SmartRefresh 

= 

TAG_USER 

+ 

141 

WA_SizeBRight 

= 

TAG_USER 

+ 

142 

WA_SizeBBottom 

= 

TAG_USER 

+ 

143 

WA_AutoAd j  ust 

= 

TAG_USER 

+ 

144 

WA_GimmeZeroZero 

= 

TAG_USER 

+ 

145 

Dec  Hex  STRUCTURE  ColorSpec , 0 
0   $0  WORD   cs_Color Index 
2   $2  UWORD  cs_Red 


;18  bit  color  value  (2.0) 
; index  or  -1 
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4   $4  UWORD  cs_Green 
6   $6  UWORD   cs_Blue 
8   $8  LABEL   cs_SIZEOF 


Dec 

Hex  STRUCTURE  Menu, 0 

menu 

0 

$0  APTR 

mu_NextMenu 

next  menu 

4 

$4  WORD 

mu_LeftEdge 

position 

6 

$6  WORD 

mu_TopEdge 

8 

$8  WORD 

mu_Width 

box  size 

10 

$A  WORD 

mu_Height 

12 

$C  WORD 

mu_Flags 

see  below 

14 

$E  APTR 

mu_MenuName 

menu  text 

18 

$12  APTR 

mu_FirstItem 

first  Menultem 

22 

$16  WORD 

mu_JazzX 

box  with  all  Menu I terns 

24 

$18  WORD 

mu_JazzY 

26 

$1A  WORD 

mu_BeatX 

28 

$1C  WORD 

mu_BeatY 

30 

$1E  LABEL 

mu_SIZEOF 

MENUENABLED  =  1 
MIDRAWN  =   $100 


;menu  can  be  selected 
; Items  are  drawn 


Dec  Hex  STRUCTURE  Menultem, 0 

0   $0  APTR  mi_NextItem 

4   $4  WORD  mi_LeftEdge 

6   $6  WORD  mi_TopEdge 

8   $8  WORD  mi_Width 

10   $A  WORD  mi_Height 

12   $C  WORD  mi_Flags 

14   $E  LONG  mi_MutualExclude 

18  $12  APTR  mi_ItemFill 

22  $16  APTR  mi_SelectFill 

26  $1A  BYTE  mi_Command 

27  $1B  BYTE  mi_KludgeFi 1 1 0 0 

28  $1C  APTR  mi_SubItem 

32  $20  WORD  mi_NextSelect 

34  $22  LABEL  mi_SIZEOF 


; Menultem,  Subltem 
;next  Menultem 
;position 

i 

;size 

;see  below 

; exclude 

; Image,  IntuiText  or  0 

; Image,  IntuiText  or  0 

;key  code 

; Subltem  (only  with  Menultems) 
/when  selected 


CHECKIT  =     1  ; check  when  selected 

ITEMTEXT  =     2  ; . . .Fill  points  to  IntuiText 

COMMSEQ  =     4  ;with  Amiga  key  code 

MENUTOGGLE  =     8  /toggle  when  selected 

ITEMENABLED  =  $10  /selection  possible 

HIGHFLAGS  =  $C0  /display  mode  for  Flags 

HIGHIMAGE  =     0  /mi_SelectFill  when  activated 

HIGHCOMP  =  $40  /compliment  Item  region 

HIGHBOX  =  $80  /draw  border  around  item 

HIGHNONE  =  $C0  /do  not  react 
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CHECKED     =   $100  ;if  CHECKIT:  Item  is  checked 

ISDRAWN     =  $1000  ,-SubItems  are  drawn 

HIGHITEM    =  $2000  ; Item  is  activated 

MENUTOGGLED  =  $4000  ; Item  has  been  toggled 


NOMENU 

= 

$1F 

NOITEM 

= 

$3F 

NOSUB 

= 

$1F 

MENUNULL 

= 

$FFFF 

CHECKWIDTH  =  19 
COMMWIDTH  =  27 
LOWCHECKWIDTH  =13 
LOWCOMMWIDTH   =16 


0   $0  STRUCT 

im_ 

.ExecMessage, MN_SIZE 

20  $14  LONG 

im_Class 

;IDCMP  event 

24  $18  WORD 

im. 

.Code 

.•associated  data  (key 

26  $1A  WORD 

im. 

.Qualifier 

;copy  of  InputEvent 

28  $1C  APTR 

im. 

.1 Address 

; object  address 

32  $20  WORD 

im. 

.MouseX 

; mouse  coordinates 

34  $22  WORD 

im. 

.MouseY 

; 

36  $24  LONG 

im. 

.Seconds 

;time 

40  $28  LONG 

im. 

.Micros 

* 

44  $2C  APTR 

im. 

.IDCMPWindow  ; window 

48  $30  APTR 

im. 

.SpecialLink  ; internal  link 

52  $34  LABEL 

im. 

.SIZEOF 

SIZEVERIFY 

= 

1 

;before  change  in  size 

NEWSIZE 

= 

2 

;new  window  size 

REFRESHWINDOW 

= 

4 

.•refresh  window 

MOUSEBUTTONS 

= 

8 

;mouse  buttons 

MOUSEMOVE 

= 

$10 

; mouse  movements 

GADGETDOWN 

= 

$20 

/gadget  selected 

GADGETUP 

= 

$40 

; gadget  released 

REQSET 

= 

$80 

/Requester  appeared 

MENUPICK 

= 

$100 

;menu  selection 

CLOSEWINDOW 

= 

$200 

; close  window 

RAWKEY 

= 

$400 

;raw  key  code 

REQVERIFY 

= 

$800 

/before  Requester 

REQCLEAR 

= 

$1000 

/Requester  cleared 

MENUVERIFY 

= 

$2000 

/prior  to  menu  display 

NEWPREFS 

= 

$4000 

/preferences  changed 

DISKINSERTED 

= 

$8000 

/disk  inserted 

DISKREMOVED 

= 

$10000 

/disk  removed 

WBENCHMESSAGE 

= 

$20000 

j for  Open/CloseWorkbench 

ACTIVEWINDOW 

= 

$40000 

/active  window 

code,  etc.) 
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INACTIVEWINDOW 

DELTAMOVE 

VANILLAKEY 

INTUITICKS 

IDCMPUPDATE 

MENUHELP 

CHANGEWINDOW 

LONELYMESSAGE 


$80000  .-window  deactivated 

$100000  /relative  mouse  movement 

$200000  ;ASCII  characters  and  strings 

$400000  ;l/50  second  impulse 

$800000  ;for  BOOPSI  Gadgets 

$1000000  ;HELP  with  menu  selection 

$2000000  ;window  position/size  changed 

$80000000  ; invalid  message  (internal) 


MENUHOT     =  1  ; check  MENUCANCEL  (MENUVERIFY) 
MENUCANCEL   =  2  ; cancel  menu  operation?  (MENUVERIFY) 
MENUWAITING  =  3  ,-waiting  for  ReplyMsgO 

OKOK         =  MENUHOT     ;does  not  matter 
OKABORT     =  4  ;aha,  draw  the  window 

OKCANCEL     =  MENUCANCEL  ;aha,  cancel 


WBENCHOPEN 
WBENCHCLOSE 


1  ;for  WBENCHMESSAGE 
2 


SELECTUP  =  (IECODE_LBUTTON+IECODE_UP_PREFIX) 

SELECTDOWN  =  (IECODE_LBUTTON) 

MENUUP  =  (IECODE_RBUTTON+IECODE_UP_PREFIX) 

MENUDOWN  =  ( IECODE_RBUTTON) 

ALTLEFT  =  (IEQUALIFIER_LALT) 

ALTRIGHT  =  (IEQUALIFIER_RALT) 

AMIGALEFT  =  (IEQUALIFIER_LCOMMAND) 

AMIGARIGHT  =  (IEQUALIFIER_RCOMMAND) 

AMIGAKEYS  =  ( AMIGALEFT+AMIGARIGHT) 

CURSORUP  =  $4C 

CURSORLEFT  =  $4F 

CURSORRIGHT  =  $4E 

CURSORDOWN  =  $4D 

KEYCODE_Q  =  $10 

KEYCODE_X  =  $32 

KEYCODE_N  =  $3  6 

KEYCODE_M  =  $37 

KEYCODE_V  =  $34 

KEYCODE_B  =  $35 
KEYCODE_LESS     =  $38 
KEYCODE_GREATER  =  $39 
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3.  Requesters 


lAutoRequest  Display  and  query  requester | 

Cfl/l.'         Response  =  AutoReguest (Window,  BodyText,  PosText,  NegText,  PosFlags,  NegFlags) 
DO         -348(A6)    AO      Al        A2       A3       DO        Dl 


BOOL   Response 

STRUCT  Window  'Window 

STRUCT  IntuiTexc  *BodyText,  *PosText,  *NegText 

ULONG  PosFlags,  NegFlags 

Function:  Opens  a  window  and  displays  the  Okay-Cancel  requester. 
Both  gadgets  can  be  activated  by  clicking  or  by  incoming 
IDCMP  events.  Warning:  prior  to  AmigaOS  2.0,  the  size  of 
the  requester  window  must  be  given  -  WORD  width  (D2), 
height  (D3). 

Parameters:  Window  Window  structure  of  the  window  to  be  locked. 

BodyText  IntuiText  structure(s)  of  the  requester. 

PosText  IntuiText  structure  for  'Okay'  or  0. 

NegText  IntuiText  structure  for  'Cancel'. 

PosFlags  IDCMP  flags  for 'Okay'. 

NegFlags  IDCMP  flags  for  'Cancel'. 

Result:  0  'Cancel' 

|  BuildEasyRequest Args  Create  system  requester | 

Cfl//.'         ReqWindow      BuildEasyRequestArgs(  RefWindow,  easystruct,  IDCMP,  Args  ) 
DO         -594  (A6)  AO        Al         DO     A3 

STRUCT  Window  *ReqWindow,  *Refwindow 
STRUCT  Easystruct  *easystruct 

ULONG   IDCMP 
APTR   Args 
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Function:      Displays  a  requester  in  a  new  window. 
Parameters:  Window     Window  locked  by  the  requester. 

easyStruct  EasyStruct  of  the  requesters. 

IDCMP       Flags  of  the  requester  window. 

Args  See  EasyRequest() 

Result:  The  address  of  the  requester  window  or  0  (error,  cancel)  or 

1  (error,  continue). 

IBuildSysRequest  Create  system  requester  (old)  | 

K^all:  Reqwindow  =  BuildSysRequest  (Window,  BodyText,  PosText,  NegText,  IDCMPFlags) 

DO  -360IA6)        AO      Al        A2       A3       DO 

STRUCT  Window  'Reqwindow,  -window 

STRUCT  IntuiText  *BodyText, *PosText, *NegText 

ULONG  IDCMPFlags 

Function:  Displays  a  system  requester.  Warning:  prior  to  AmigaOS  2.0 
the  window  size  must  be  given  (WORD  Width.Height 
D2/D3). 

Parameters:  Window     Window  to  be  locked 

BodyText  Requester  text 

PosText      Positive  gadget  text 

NegText     Negative  gadget  text 

IDCMPFlags 

Flags  for  the  requester  window. 

Result:  Window  of  the  requesters  or  0  (error)  or  1  (pre-OS  2.0). 
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1  ClearDMRequest  Clear  double  menu  requester  | 

Call:  Response  =  ClearDMRequest  (Window) 

DO  -48 (A6)  AO 

BOOL       Response 
STRUCT  Window  *Window 

Function:  Attempts  to  remove  the  requester  that  appears  when  the 
right  mouse  button  is  double-clicked. 

Parameters:  Window     Window  with  DMRequest 

Result:  0  Requester  is  active  and  could  not  be  removed. 

|  Display  Alert  Display  and  query  alert  message  | 

Call:  Response  =  DisplayAlert (AlertNumber,  String,  Height) 

DO  -90 (A6)       DO  AO       Dl 

BOOL  Response 
ULONG  AlertNumber 
APTR  String 
WORD  Height 

Function:  Displays  the  text  defined  in  the  alarm  string  on  a  black 
display  using  the  Topaz/8  font.  DeadEnds  are  in  red  and 
Recoverables  are  in  amber.  The  alarm  string  is  constructed 
as  follows: 

•  16  bit  X  coordinate 

•  8  bit  Y  coordinate 

•  String  ending  with  0 

•  Byte  flag  for  another  string  (1  or  0  (=end)) 

Parameters:  AlertNumber 

Exec  alert  code  (only  bit  31  is  important) 

String         Alarm  string  address 

Height        Required  display  height 
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DeadEnd  or  right  mouse  button,  TRUE  =  left 
mouse  button. 


Example :      Display  a  multi-line  alarm  message: 


movea.l  _IntuiBase,a6 

moveq   #0,d0  ; Recoverable  Alert 


lea 

_Meldung 

(pc) 

,a0 

; special  string 

moveq 

#38, dl 

; height 

jsr 

_LVODisplayAlert(a6)  .-display 

tst.l 

dO 

bne 

_Okay 

_>feldung 

dc.b 

1,40 

;x  coordinate:  1*256+40 

dc.b 

7+10 

;y  coordinate 

dc.b 

'Hallo! " 

,0 

;  text 

dc.b 

1 

;not  ended  yet 

dc.b 

0,20 

dc.b 

7+20 

dc.b 

'Links 

HALLO ! '  ,  0 

dc.b 

1 

dc.b 

1,248 

dc.b 

7+20 

dc.b 

■ Rechts 

?# 

IS  '.0 

dc.b 

0 

;end 

I  Easy  Request  Args 


Query  with  requester] 


Call: 


GGNum  =  EasyRe<juestArgs(  Window,  easyStruct,  IDCMP_ptr,  ArgList  ) 
DO  -588 <A6)         A0      Al         A2        A3 


STRUCT  Window  *window 
APTR   IDCMP_pcr,Args 
STRUCT  EasyStruct  *easyStruct 
LONG   GGNum 


Function:  Display  system  requester  with  desired  gadgets  and 
formattable  text  in  such  a  way  that  the  requester  is 
optimized  with  respect  to  the  screen  resolution  and  the  font 
size. 
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Parameters:  Window     Parent  window  or  0  (default  PublicScreen, 

usually  Workbench) 

IDCMP_ptr 

Address  of  IDCMP  flags  for  ending. 

easyStruct  EasyStruct  structure: 

es_StructSize:  EasyStructJSIZEOF 

es_Flags:  0 

es_Tide: 


Result: 


es_TextFormat: 


Window  title  or  0  (title  of 
AO) 

RawDoFmtO  format  for 
query  (also  W) 


Args 


es_GadgetFormat:    Format  string  for  gadgets; 
gadgets  are  separated  by 


Arguments    for    TextFormat,    then    for 
GadgetFormat. 


Selected  gadget  number  (numbering:  l,2,...,x,0)  or  -1 
(IDCMP:  event  in  *IDCMP_ptr). 


tst.b   _FileName 
beq     _LoadIt 


movea.l  _IntuiBase,a6 

movea.l  _Window,aO 

lea     _EasyStruct (pc) ,  al 

lea     _IDCMP(pc) ,a2 

lea     _FileName,a3 

j  sr     _LVOEasyRequestArgs ( a6 ) 

tst.l   dO 

bne     _LoadIt 


Example:      Security  prompt  for  a  word  processor  when  the  '  LOAD 
TEXT  menu  item  is  selected: 

;load   file? 
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Loadlt 


_IDCMP 
del    0 

_EasyStruct 
del   es_SIZEOF,  0,_Title,_Fmt,_Buttons 

JTitle 

dc.b  "load  text'  ,0 
_Fmt 

dc.b  'the  file  %s  has  not  yet  been  saved. ',0 
_Buttons 

dc.b  ' Load  I  Return ', 0 


_FileName 
ds.b  256        ; contains  current  file  name 


lEndRequest  Remove  requester] 

Call:  EndRequest  (Requester,   window) 

-120 (A6)         A0  Al 

STRUCT  Requester  *Requester 
STRUCT  Window  *Window 

Function:     Removes  the  currently  active  requester  (makes  it  inactive). 

Parameters:  Requester  Requester  to  be  removed 

Window     Locked  window 

I  FreeSysRequest  Free  a  system  requester  1 

Call:  FreeSysRequest  (Window) 

-372 (A6)  A0 

STRUCT  Window  *Window 

Function:     Frees    a    system   requester   that   was    created    with 
BuildSysRequestQ  or  BuildEasyRequestQ. 
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Parameters:  Window     Window   of  the   requester   (result   of  the 

Build...Request()  functions).  The  values  0  and  1 
have  no  effect. 

1  InitRequester  Initialize  requester  structure  | 

Call:  InitRequester  (Requester) 

-138 (A6)       AO 

STRUCT  Requester  *Requester 

Function:  Initializes  a  requester  structure.  After  the  call,  the  structure 
must  be  loaded  with  user  data.  This  is  a  C  routine,  which  is 
seldom  or  never  used  because  of  the  speed  of  execution. 

Parameters:  Requester  Requester  structure 

|  Request  Display  requester  | 

Call:  Success  =  Request (Requester,   window) 

DO  -240 (A6)    AO  Al 

BOOL       Success 

STRUCT  Requester  *Requester 

STRUCT  window  *Window 

Function:     Displays  a  requester  in  a  window  (POINTREL  now  works). 

Parameters:  Requester  Requester  to  be  displayed 

Window     Window 

Result:  0  Error 

ISetDMRequest  Define  double  menu  requesterl 

Call:  success  =  SetDMRequest  (Window,   DMRequester) 

DO  -258 (A6)  AO  Al 

BOOL       success 

STRUCT  Window  *Window 

STRUCT  Requester   *DMRequester 
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Function:      Attempts  to  define  the  DMRequester.  This  will  not  work  if 
another  DMRequester  is  active.  POINTREL  works. 

Parameters:  Window     Window 

DMRequester 

Requester  for  menu  key  double-click. 

Result:  0  Error,  DMRequest  now  active. 

[SysReqHandler  Query  system  requester  | 

Call:  num   SysReqHandler (  Window,  IDCMPFlagsPtr,  Waitlnput  ) 

DO   -600  A0      Al  DO 

STRUCT  Window  *Window 
CPTR   IDCMPFlagsPtr 
BOOL   Waitlnput 

Function:      Queries  a  system  requester. 

Parameters:  Window     Result  from  Build...Request(). 

IDCMPFlagsPtr 

Address  of  the  IDCMP  flags. 

Waitlnput  Boolean:  wait  for  input. 

Result:  Like  EasyRequest(),  -2  also  possible  (no  input). 

Dec  Hex  STRUCTURE  EasyStruct , 0 

0   $0  ULONG  es_StructSize  ;es_SIZEOF 

4   $4  ULONG  es_Flags  ;0 

8   $8  APTR  es_Title  ; Requester  title 

12   $C  APTR  es_TextFormat  ; format  string  for  BodyText 

16  $10  APTR  es_GadgetFormat  ; format  string  for  Gadgets 

20  $14  LABEL  es_SIZEOF  ;size  of  structure 

Dec  Hex  STRUCTURE  Requester, 0 

0   $0  APTR   rq_01derRequest  ; older  Requester 
4   $4  WORD   rq_LeftEdge      ; position 
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6   $6  WORD  rq_TopEdge 

8   $8  WORD  rq_Width 

10   $A  WORD  rq_Height 

12   $C  WORD  rq_RelLeft 

14   $E  WORD  rq_RelTop 

16  $10  APTR  rq_ReqGadget 

20  $14  APTR  rq_ReqBorder 

24  $18  APTR  rq_ReqText 

28  $1C  WORD  rq_Flags 

30  $1E  UBYTE  rq_BackFill 

31  $1F  BYTE  rq_KludgeFill00 

32  $20  APTR  rq_ReqLayer 
36  $24  STRUCT  rq_ReqPadl, 32 
68  $44  APTR  rq_ImageBMap 
72  $48  APTR  rq_RWindow 

76  $4C  APTR  rq_ReqImage 

80  $50  STRUCT  rq_ReqPad2,32 

112  $70  LABEL  rq_SIZEOF 


position  relative  to  mouse 

Gadgets 
border 
IntuiTexts 
see  below 
Requester  color 

; Layer 

;BitMap  with  complete  Requester 

/window 

;v2.0:  Images  after  Backfill 


POINTREL      =     1  ,-display  relative  to  mouse  or  center  of  window 

PREDRAWN      =     2  ;  graphic  from  ImageBMap 

NOISYREQ      =     4  ;do  not  filter  input 

SIMPLEREQ     =    $10  ;with  SIMPLEREFRESH  Layer  (2.0) 

USEREQIMAGE   =    $20  ;with  Images  after  Backfill,  before  GGs 

NOREQBACKFILL  =   $40  ;do  not  fill  background 

REQOFFWINDOW  =  $1000  ,-Gadget  component  outside  Requester 

REQACTIVE     =  $2000  ,-Requester  is  active 

SYSREQUEST    =  $4000  ,-Requester  generated  by  system 

DEFERREFRESH   =  $8000  ,-Requester  stops  Refresh 

ALERT_TYPE      =  $80000000  ;mask 
RECOVERY_ALERT   =  0 

DEADEND_ALERT   =  $80000000  ; crash 


Example:  Display  and  query  EasyRequest.  The  requester  that  follows 
indicates  insufficient  ChipMem  until  enough  can  be 
reserved  after  a  'Retry'  or  'Cancel'  is  selected.  The  result  is 
the  memory  block  allocated  with  Alloc Vec(): 


_AskForHelp 
movem.l  a2-a4/a6, -(a7) 

movea.l  _IntuiBase,a6 
movea.l  _Window,a0 
lea     _EasyReque  s  t ( pc ) , a 1 
lea     _IDCMP(pc),a2 
lea     _NeededMem(pc) ,a3 
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jsr      _LV0BuildEasyRequestArgs(a6) 
subq.l   #l,dO 
ble.s   _Failure 
addq.l   #l,dO 
movea .1  dO , a4 

_Loop 

movea .1  a4 , aO 

lea  _IDCMP(pc) ,al 

moveq  #-l,dO 

jsr  _LVOSysReqHandler (a6) 

tst.l  dO 

beq . s  _Break 

bpl.s  _Retry 

addq.l  #2,d0 

beq . s  _Loop 

bra . s  _Break 

_Retry 

movea . 1  _Sy sBase , a6 

move.l  (a3),d0 

move.l  #MEMF_CLEAR!MEMF_CHIP,dl 

j  sr  _LVOAllocVec (a6 ) 

movea . 1  _IntuiBase , a6 

tst.l  dO 

beq .  s  _Loop 

_Break 
movea .1  dO , a3 
movea .1  a4 , aO 

j  sr     _LVOFreeSysRequest (a6 ) 
move .1  a3 , dO 
bra.s   _Exit 

_Failure 
moveq   #0,d0 

_Exit 
movem.l  (a7)+, a2-a4/a6 
rts 

_NeededMem 
del  256000 

_IDCMP 
del  0 

_EasyRequest 
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del  es_SIZEOF,0,_Title,_Fmt,_Buttons 

_Title 

dc.b  "Not  enough  memory' ,0 
_Fmt 

dc.b  'I  need  %ld  byte  chipmem!',0 
.Buttons 

dc.b  ' Retry  I  Cancel' ,0 

4.  Gadgets 

lActivateGadget  Activate  string  or  GadTools  gadget! 

Call:  Success  =  ActivateGadget (Gadget,  Window,  Request) 

DO        -462 (A6)       A0      Al      A2 

BOOL   Success 
STRUCT  Gadget  *Gadget 
STRUCT  Window  *Window 
STRUCT  Requester  *Request 

Function:     Activates  a  string  or  CustomGadget. 

Parameters:  Gadget       String  or  CustomGadget 

Window     Active  window  with  the  gadget 
Requester  Requester  if  GTYP_REQGADGET 

Result:  0  Gadget  not  activated 

|  AddGadget  Add  gadget  to  the  window  list  I 

Call:  RealPosition  =  AddGadget (Window,  Gadget,  Position) 

DO  -42 (A6)    A0      Al      DO 

UWORD  RealPosition, Position 
STRUCT  Window  *Window 
STRUCT  Gadget  *Gadget 

Function:     Adds  a  gadget  to  a  window  list. 
Parameters:  Window     Window  structure  of  the  window. 
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Gadget       Gadget  structure 

Position      Position  in  the  list  (0...65535). 

Result:  Position  at  which  the  gadget  was  inserted  in  the  list 

(0...65535). 

|  AddGList  Add  gadgets  to  the  window  list  | 

Call:  RealPosition  =  AddGList  (Window,  Gadget,  Position,  Numgad,  Requester) 

DO  -438  (A6)  AO      Al      DO        Dl      A2 

UWORD  RealPosition,  Position,  Numgad 
STRUCT  Window  *window 
STRUCT  Gadget  *Gadget 
STRUCT  Requester  *Requester 

Function:      Adds  liked  gadgets  to  a  window  list. 
Parameters:  Window     Window  structure  of  the  window. 

Gadget       First  gadget  to  insert. 

Position      Position  in  the  list  (0...65536  NumGads). 

Numgad     Number  of  gadgets  or  -1  (all). 

Requester  Requester,  if  GTYP_REQGADGET. 

Result:  Position  at  which  the  gadgets  were  inserted  in  the  list 

(0...65535). 

IGadgetMouse  Gadget-relative  mouse  position  | 

Call:  GadgetMouse(   Gadget,   GInfo,   MousePoint   ) 

-570  (A6)  AO  Al  A2 

STRUCT  Gadget   *Gadget 
STRUCT  Gadget Info  *GInfo 
STRUCT  Point   *MousePoint 


399 


3.  Programming  with  AmigaOS  2.x 


Function:      Calculates  the  gadget-relative  mouse  position  (completely 
meaningless,  since  this  information  is  always  available). 

Parameters:  GInfo         Gadgetlnfo  structure  for  the  hook  routine. 

MousePoint 

Address  of  two  words  for  the  position. 

Gadget       Desired  gadget 

|  Modify  Prop  Modify  proportional  gadget  | 

Cfl//.'        Modi fyProp( Gadget,  Window,  Requester,  Flags,  HorizPot,  VertPot, 
HorizBody,  VertBody) 
-156  (A6)    AO      Al      A2       DO      Dl      D2       D3 

D4 

STRUCT  Gadget  *Gadget 

STRUCT  Window  *Window 

STRUCT  Requester  "Requester 

UWORD  Flags, HorizPot, VertPot, HorizBody,  VertBody 

Function:     Changes  the  contents  of  a  PropGadget  and  executes  a 
complete  refresh  of  the  gadget  and  all  following  gadgets. 

Parameters:  Gadget       PropGadget 

Window     Window  of  the  gadgets 

Requester  Requester  or  0 

Rags,...Pot,...Body 

Values  for  Proplnfo 

INewModifyProp  Change  proportional  gadget  I 


Call: 


NewModi f yProp ( Gadget,  window.  Requester,  Flags,  HorizPot,  VertPot,  HorizBody, 
VertBody,  NumGad) 

-468  (A6)       AO      Al       A2  DO      Dl         D2        D3 

D4       DS 

STRUCT  Gadget  'Gadget 
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STRUCT  Window  *Window 

STRUCT  Requester  *Requester 

UWORD  Flags,  HorizPot,VertPot,HorizBody,VertBody 

WORD   NumGad 

Function:  Like  ModifyPropO,  but  this  function  allows  you  to  specify 
how  many  gadgets  should  be  refreshed.  A  value  of  1  will 
cause  only  the  knob  to  be  refreshed. 

Parameters:  NumGad     Number  of  gadgets  to  refresh,  -1  (all),  or  1  (knob 

only). 

See  ModifyPropO 

IQbtainGIRPort  Allocate  RastPort  for  a  CustomGadgetl 

Call:  RPort  =  ObtainGIRPort  (   GInfo   ) 

DO  -558 (A6)  AO 

STRUCT  RastPort   *RPort 
STRUCT  Gadgetlnfo   *GInfo 

Function:  Allocates  the  RastPort  of  a  CustomGadget  and  initializes  it 
for  a  hook  routine. 

Parameters:  GInfo  Gadgetlnfo  structure  of  the  CustomGadget. 

Result:  RastPort  or  0 

IQffGadget  Turn  gadget  offl 

Call:  Off  Gadget  (Gadget,  window,  Requester) 

-174 (A6)   AO      Al      A2 

STRUCT  Gadget  *Gadget 
STRUCT  Window  *Window 
struct  Requester  *Requester 

Function:  Turns  a  gadget  off.  The  gadget  is  displayed  as  a  ghost  and 
cannot  be  selected.  Also  refreshes  all  gadgets. 

Parameters:  Gadget       Gadget  to  turn  off 
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Window     Gadget  window 

Requester  Requester  if  GTYP_REQGADGET 

| OnGadget  Turn  gadget  on | 

Call:  OnGadget  (Gadget,   Window,   Requester) 

-186 (A6)    AO  Al  A2 

STRUCT  Gadget  *Gadget 
STRUCT  Window  *Window 
STRUCT  Requester  * Requester 

Functions,  Parameters: 

Opposite  of  OffGadget().  Allows  selection  of  the  gadget 
again. 

IRefreshGadgets  Refresh  gadgets  | 

Call:  RefreshGadgets (Gadgets,   Window,   Requester) 

-222  (A6)  AO  Al  A2 

STRUCT  Gadget   *Gadgets 
STRUCT  Window  *Window 
STRUCT  Requester  *Requester 

Function:     Refreshes  all  GGs  starting  with  the  given  gadget. 

Parameters:  Gadgets      Address  of  the  first  gadget. 

Window      Gadget  window 

Requester  Requester  or  0 
IRefreshGList  RefreshGListl 

Call:  RefreshGList (Gadgets,  Window,  Requester,  NumGad) 

-432  (A6)      AO       Al      A2         DO 

STRUCT  Gadget  *Gadgets 
STRUCT  Window  *Window 
STRUCT  Requester  *Requester 
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WORD        NumGad 

Function:      Similar  to  RefreshGadgets(),  but  only  allows  you  to  specify 
the  number  of  gadgets  to  refresh. 

Parameters:  NumGad     Number  of  gadgets,  -1  (all)  or  -2  (all  requester 

gadgets). 

See  RefreshGadgets() 

I  ReleaseGIRPort  Free  CustomGadget  RastPort] 

Call:  ReleaseGIRPort  (  RPort   ) 

-564 (A6)  AO 

STRUCT  RastPort   *RPort 

Function:      Free  a  RastPort  allocated  with  ObtainGIRPort(). 

Parameters:  RPort  Result  of  ObtainGIRPort()  or  0. 

|  RemoveGadget  Remove  a  gadget  from  the  window  list| 

Call:  Position  =  RemoveGadget (Window,   Gadget) 

DO  -228 (A6)  AO  Al 

UWORD     Position 
STRUCT  Window  *Window 
STRUCT  Gadget   *Gadget 

Function:     Removes  a  gadget  from  the  window  list.  If  it's  active,  it  is 
first  deactivated. 

Parameters:  Window     Gadget  window 

Gadget       Gadget  to  be  removed 

Result:  Position  of  the  gadget  or  -1  if  it  was  not  in  the  list  (or 

gadget  #65535). 
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IRemoveGList 


Remove  gadgets  from  the  window  list| 


Call:  Position  =  RemoveGList  (Window,  Gadget,  Numgad) 

DO         -444 (A6)     AO      Al      DO 

UWORD  Position 
STRUCT  Window  *Window 
STRUCT  Gadget  *Gadget 
WORD   Numgad 

Function:  Removes  several  gadgets  from  the  window  list  and  clears 
gg_NextGadget  for  the  last  gadget  removed.  If  the  active 
gadget  is  included,  it  is  first  deactivated. 

Parameters,  Result: 

Numgad      Number  of  gadgets  or  - 1  (all) 

See  RemoveGadgetQ 


IReportMouse 


Change  ReportMouse  flag| 


Call:  ReportMouse  (Window,  Boolean) 

-234 (A6)  AO  DO 

BOOL       Boolean 
STRUCT  Window  *Window 

Function:  Changes  the  ReportMouse  flag  of  the  window  and  the 
FollowMouse  flag  of  the  active  gadget.  If  a  gadget  is  active 
when  the  call  is  made,  the  change  is  only  good  at  the  time 
of  gadget  activation.  C  compilers  often  make  errors  with 
this  function  because  the  order  of  the  two  parameters  is 
often  switched. 


Parameters:  Window     Window 

Boolean     TRUE  or  0  (bit  status) 
ISetEditHook 


Call:  OldHook  =  SetEditHook  (  Hook) 

DO  -492 (A6)  AO 


Set  StringGadget  hook  | 
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STRUCT   Hook    *OldHook,*Hook 

Function:  Defines  the  global  editor  hook  for  StringGadgets.  This  does 
not  just  include  its  own  gadgets;  this  should  be  used  only 
in  highly  optimized  Assembler  code. 

Parameters:  Hook  Hook     with     editor    routine     for     ALL 

StringGadgets. 

Result:  Hook  of  the  previous  editor  routine. 

Warning:  Since  this  routine  has  not  been  tested  by  Commodore  yet, 
you  should  not  use  it. 

ISetGadgetAttrsA  Set  gadget  attributes  of  a  BoopsiGadgetl 

Call:  Result  =  SetGadgetAttrsA(  Gadget,  Window,  Requester,  TagList  ) 

DO   -660  (A6)         A0      Al      A2         A3 

STRUCT  Gadget  *Gadget 
STRUCT  Window  *Window 
STRUCT  Requester  *Requester 
STRUCT  Tagltem  *TagList 
LONG  Result 

Function:  Like  SetAttrs(),  with  context  information  for 
CustomGadgets. 

Parameters:  Gadget  Boopsi  object 

Window  Object's  window 

Requester  For  REQGADGETs 

TagList  Tagltem  field 

Result:  Not  0:  Gadget  must  be  refreshed  to  display  the  new 

attributes. 
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Dec  Hex  STRUCTURE  Gadgetlnfo, 0 
0   $0  APTR   ggi_Screen 
4   $4  APTR   ggi_Window 
8   $8  APTR    ggi_Requester 

12   $C  APTR   ggi_RastPort 

16  $10  APTR   ggi_Layer 

20  $14  STRUCT  ggi_Domain, ibox_SIZEOF 

28  $1C  STRUCT  ggi_Pens,2 

3  0  $20  APTR   ggi_DrInfo 

Dec  Hex  STRUCTURE  I Box, 0 


0  $0  WORD 

2  $2  WORD 

4  $4  WORD 

6  $6  WORD 


ibox_Left 
ibox_Top 
ibox_Width 
ibox_Height 


8   $8  LABEL   ibox_SIZEOF 


Dec  Hex 
0   $0 


STRUCTURE 
APTR   gg. 


4 

6 

8 

10 

12 

14 


$4 
$6 
$8 
$A 
$C 
$E 


16  $10 
18  $12 
22  $16 
26  $1A 
30  $1E 
34  $22 
38  $26 
40  $28 
44  $2C 


WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
APTR 
APTR 
APTR 
LONG 
APTR 
WORD 
APTR 
LABEL 


gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 
gg. 


Gadget , 0 
.NextGadget 
.LeftEdge 
.TopEdge 
.Width 
.Height 
_Flags 
.Activation 
.GadgetType 
.GadgetRender 
.SelectRender 
.GadgetText 
.Mutua  1  Exc  lude 
.Speciallnfo 
.Gadget  ID 
.UserData 
.SIZEOF 


next  Gadget 
position 

size 

see  below 

see  below 

see  below 

Border,  Image  or  Null 

Border,  Image  or  Null 

IntuiText  or  Null 

CustomGadget  Hook 

according  to  GadgetType 

User  ID 

User  data 


GADGHIGHBITS  =  3  ;  selection  Flags 

GADGHCOMP  =  0  ; complement 

GADGHBOX  =  1  ;box 

GADGHIMAGE  =  2  ;use  SelectRender 

GADGHNONE  =  3  ;no  reaction 

GADGIMAGE  =  4  ;... Render  is  Image  structure 

GRELBOTTOM  =  8  ; coordinates  relative  to  bottom 

GRELRIGHT  =  $10  ; coordinates  relative  to  right  edge 

GRELWIDTH  =  $20  ; width  relative  to  window  width 

GRELHEIGHT  =  $40  ; height  relative  to  window  height 

SELECTED  =  $80  ;Gadget  is  in  selected  mode 

GADGDISABLED  =  $100  ,-Gadget  is  disabled 

LABELMASK  =  $3000  .-meaning  of  gg_GadgetText 
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LABELITEXT    =      0  ;GadgetText  is  IntuiText 
LABELSTRING   =  $1000  ;GadgetText  is  string 
LABELIMAGE    =  $2000  ;GadgetText  is  Boopsi Image 


RELVERIFY 

GADGIMMEDIATE 

ENDGADGET 

FOLLOWMOUSE 

RIGHTBORDER 

LEFTBORDER 

TOPBORDER 

BOTTOMBORDER 

BORDERSNIFF 

TOGGLESELECT 

BOOLEXTEND 

STRINGC ENTER 

STRINGRIGHT 

LONGINT 

ALTKEYMAP 

STRINGEXTEND 

ACTIVEGADGET 


1 

2 

4 

8 

$10 

$20 

$40 

$80 

$8000 

$100 

$2000 

$200 

$400 

$800 

$1000 

$2000 

$4000 


activation:  only  within  Box 

activate  immediately 

ends  Requester 

ReportMouse  during  selection 

right  border 

left  border 

title  bar 

bottom  border 

private 

toggle  when  selected 

Boollnfo  in  gg_SpecialInfo 

center  StringGG  contents 

right  justify  StringGG  contents 

StringGadget  for  integer  values 

StringGadget  with  another  KeyMap 

StringGadget  extended 

Gadget  is  active 


GADGETTYPE 

SYSGADGET 

SCRGADGET 

GZZGADGET 

REQGADGET 

SIZING 

WDRAGGING 

SDRAGGING 

WUPFRONT 

SUPFRONT 

WDOWNBACK 

SDOWNBACK 

CLOSE 

BOOLGADGET 

GADGET0002 

PROPGADGET 

STRGADGET 

CUSTOMGADGET 


$FC00 

$8000 

$4000 

$2000 

$1000 

$10 

$20 

$30 

$40 

$50 

$60 

$70 

$80 

1 

2 

3 

4 

5 


,-global  GadgetTypes 

;operating  system  Gadget 

; screen  Gadget 

/Gadget  for  window  borders 

.•Requester  Gadget 

.•sizing  Gadget 

,-movable  title  bar 

; same  for  Screens 

.•window  to  front 

; screen  to  front 


; close  Gadget 
;BoolGadget 


r  PropGadget 
; StringGadget 
; CustomGadget 


Dec  Hex  STRUCTURE  Boollnfo,  0 


0  $0  WORD 

2  $2  APTR 

6  $6  LONG 

10  $A  LABEL 


bi_Flags 
bi_Mask 
bi_Reserved 
bi_SIZEOF 


; BOOLMASK 
;bit  mask, 
;0 


image 


BOOLMASK 


1  ;mask 
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Dec  Hex 
0   $0 


STRUCTURE 
WORD   pi. 


$2 
$4 
$6 


8   $8 
10   $A 


12 
14 


$C 
$E 


16  $10 
18  $12 
20  $14 
22  $16 


WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
WORD 
LABEL 


PL 
Pi. 
Pi. 
Pi. 
pi. 
Pi. 
pi. 
pi. 
pi 
Pi 
Pi 


Prcplnfo, 0 
.Flags 
.HorizPot 
.VertPot 
.HorizBody 
.VertBody 
.CWidth 
.CHeight 
.HPotRes 
_VPotRes 
_LeftBorder 
.TopBorder 
.SIZEOF 


Flags  s.u. 
position 

slider  size 

container  size 

slider  resolution 

border  size 


AUTOKNOB 

FREEHORIZ 

FREEVERT 

PROPBORDERLESS 

KNOBHIT 


1  ;old  AutoKnob 

2  /horizontally  movable 
4  /vertically  movable 

8  ;no  border 

$100  /selected  Knob 


KNOBHMIN  =     6  /minimal  horizontal  size 

KNOBVMIN  =     4  /minimal  vertical  size 

MAXBODY  =  $FFFF  /maximum  Knob  size 

MAXPOT  =  $FFFF  /maximum  position 


Dec  Hex 

0   $0 


4 

8 

10 

12 

14 


$4 
$8 
$A 
$C 
$E 


16  $10 
18  $12 
20  $14 
22  $16 
24  $18 
28  $1C 
32  $20 
36  $22 


STRUCTURE 

APTR    si. 

APTR 

WORD 

WORD 

WORD 

WORD 

WORD 

WORD 

WORD 

WORD 

APTR 

LONG 

APTR 

LABEL 


si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 
si. 


Stringlnfo, 
.Buffer 
.UndoBuf  fer 
_Buf  ferPos 
.MaxChars 
.DispPos 
.UndoPos 
.NumChars 
.DispCount 
.CLeft 
.CTop 

.Extension 
.Longlnt 
.AltKeyMap 
.SIZEOF 


buffer  for  the  contents 

buffer  for  the  Undo  function 

character  position  in  buffer 

buffer  size  including  0  byte 

offset  of  the  first  displayed  character 

position  in  Undo  buffer 

length  of  string  in  buffer 

number  of  visible  characters 

offset  in  Gadget 

extension  structure  (2.0) 
value  for  integer  Gadgets 
custom  key  map 


Dec  Hex  STRUCTURE  StringExtend, 0 

0  $0  APTR   sex_Font         /TextFont  (open) 
4  $4  STRUCT  sex_Pens,2       /colors:  text,  background 
6   $6  STRUCT  sex_ActivePens,2  /colors  when  activated 
8   $8  ULONG  sex_InitialModes  /Flags 
12   $C  APTR   sex_EditHook     /edit  Hook 
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16  $10  APTR   sex_WorkBuffer 
20  $14  STRUCT  sex_Reserved, 16 

3  6  $24  LABEL   sex_SIZEOF 


;StringInfo. buffer  length 
;0 


Dec  Hex 

0   $0 


4 

8 

12 


$4 
$8 
$C 


16  $10 
20  $14 
24  $18 
26  $1A 
28  $1C 
30  $1E 
34  $22 
38  $26 
42  $2A 
44  $2C 


STRUCTURE  SGWork, 0 

APTR  sgw_Gadget 

APTR  sgw_StringInfo 

APTR  sgw_WorkBuf fer 

APTR  sgw_PrevBuf fer 

ULONG  sgw_Modes 

APTR  sgw_IEvent 

UWORD  sgw_Code 

WORD  sgw_BufferPos 

WORD  sgw_NumChars 

ULONG  sgw_Actions 

LONG  sgw_LongInt 

APTR  sgw_GadgetInfo 

UWORD  sgw_EditOp 

LABEL  sgw_SIZEOF 


Gadget 

Stringlnfo 

Intuition's  result 

previous  contents 

current  Flags 

InputEvent 

character 

CursorPosition 

number  of  characters 

what  Intuition  wants  to  do 

value  for  integer  Gadget 

Gadget Info 

editor  operation 

current  structure  size 


EditOps: 

EO_NOOP  =   1 

EO_DELBACKWARD  =   2 

EO_DELFORWARD  =   3 

E0310VECURSOR  =   4 

EO_ENTER  =   5 

EO_RESET  =   6 

EO_REPLACECHAR  =   7 

EO_INSERTCHAR  =   8 

EO_BADFORMAT  =   9 

EO_BIGCHANGE  =  10 

EO_UNDO  =11 

EO_CLEAR  =  12 

EO_SPECIAL  =  13 


nothing 

number  of  characters  to  delete  (0  allowed) 

number  of  characters  under/before  cursor  to  delete 

move  cursor 

ENTER  or  LF 

undo 

replace  character 

insert  character 

bad  input  (IntegerGadget) 

text  completely  changed 

other  Undo  operations 

clear  string 

special  functions 


SGH_REPLACE 

SGMB_REPLACE 

SGMF_REPLACE 


1  ; modes 

0 
1 


SGM_FIXEDFIELD  =  2 
SGMB_FIXEDFIELD  =  1 
SGMF_FIXEDFIELD  =  2 


SGNL.NOFILTER 

SGMB_NOFILTER 

SGMF_NOFILTER 


=4  ;do  not  filter  control 
=  2 
=  4 
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SGA_USE  =  1     ;take  contents  from  SGWork 

SGAB_USE  =  0 

SGAF_USE  =  1 

SGA_END  =  2      ;end 

SGAB_END  =  1 

SGAF  END  =  2 


SGA_BEEP 

=  4 

;DisplayBeep ( ) 

SGAB_BEEP 

=  2 

SGAF_BEEP 

=  4 

SGA_REUSE 

=  8 

; reuse  InputEv 

SGAB_REUSE 

=  3 

SGAF_REUSE 

=  8 

SGA_REDISPLAY   =  $10  ;Gadget  appearance  changed 
SGAB_REDISPLAY   =    4 
SGAF_REDISPLAY   =  $10 

SGH_KEY      =  1    ; process  keystroke 
SGH_CLICK    =  2    ,-process  mouse  click 

5.  Output  Functions 

|  Display  Beep  Cause  display  to  blink] 

Call:  DisplayBeept  Screen) 

-96 (A6)  A0 

STRUCT  Screen  *Screen 

Function:      Causes  the  entire  display  or  a  given  screen  to  blink.  This 
function  may  be  patched. 

Parameters:  Screen         Screen  to  blink  or  0 

|DrawBorder  Draw  a  border! 

Call:  DrawBorder  (RastPort,  Border,  LeftOffset,  TopOffset) 

-108 (A6)    A0         Al       DO  Dl 

STRUCT  RastPort  *RastPort 
STRUCT  Border  * Border 
WORD  LeftOffset,  TopOffset 
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Function:      Draws   the   border(s)   defined   in    the   given    Border 
structure^). 

Parameters:  RastPort  RastPort 

Border  Border  structure 

...Offset  Position  added  to  the  border  vectors. 
|  Drawlmage  ~ 


Draw  an  image  | 


Call:  Drawlmage (RastPort,  Image,  LeftOffset,  TopOffset) 

-114  (A6)   AO        Al     DO  Dl 

STRUCT  RastPort  *RastPort 

STRUCT  Image  * Image 

WORD  LeftOffset,  TopOffset 

Function:      Copies  one  or  more  bit  Bitlmages  to  the  given  RastPort. 
Parameters:  RastPort     RastPort 

Image         Image  structure 

...Offset       Position  added  to  the  image  position. 

Draw  extended  image  | 


I  DrawImageState 


Call: 


DrawImageState (RPort ,  Image,  LeftOffset,  TopOffset,  State,  Drawlnfo) 
-618  (A6)       AO     Al      DO  Dl         D2     A2 


STRUCT  RastPort  *RPort 

STRUCT  Image  *  Image 

WORD  LeftOffset, TopOffset 

ULONG  State 

STRUCT  Drawlnfo  *DrawInfo 


Function:     Draws  a  bit  image  of  the  desired  type: 

IDS_NORMAL  =  as  with  Drawlmage ( ) 

IDS_SELECTED         =  as  in  the  selected  Gadget 
IDS_DISABLED         =  as  with  disabled  Gadgets 
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IDS_BUSY  =  not  yet  supported 

IDS_INDETERMINANT    =  not  yet  supported 
IDS_INACTIVENORMAL   =  for  Gadgets  in  window  borders 
IDS_INACTIVESELECTED  =  for  Gadgets  in  window  borders 
IDS_INACTIVEDISABLED  =  for  Gadgets  in  window  borders 

Parameters:  RPort  RastPort 

Image  Image,  Customlmage,  etc. 

...Offset  Position  (offset) 

State  IDS_... 

Drawlnfo  Information  on  how  to  display  the  image. 
[Eraselmage  Erase  an  image  1 

Call:  Eraselmage!  RPort,  Image,  Leftoffset,  TopOffset  ) 

-630 (A6)     A0     Al     DO  Dl 

STRUCT  RastPort  *RPort 

STRUCT  Image  * Image 

WORD   Lef tOff set,  TopOffset 

Function:     Removes  an  image,  usually  using  graphics/EraseRect().  For 
custom  images,  it  depends  on  the  image  type. 

Parameters:  RPort  RastPort 

Image         Image  or  Customlmage 

LeftOffset,RightOffset 

Image  position  offset 

[SituiTextLength  TextLength  for  IntuiText  structure  | 

Call:  length  =  IntuiTextLength(IText) 

DO  -330 (A6)  A0 

LONG   length 

STRUCT  IntuiText  *IText 
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Function:      Gets  the  output  width  of  an  IntuiText  structure  in  pixels. 
Parameters:  IText  IntuiText  structure 

Result:  Output  width 


IPrintlText 


Output  IntuiText  | 


Call:  PrintIText(RastPort,  IText,  LeftOffset,  TopOffset) 

-216 (A6)    AO         Al      DO  Dl 

STRUCT  RastPort  *RastPort 
STRUCT  IntuiText  * IText 
WORD    LeftOffset,,,  TopOffset 

Function:      Outputs   the   text(s)   defined   in   the  given   IntuiText 
structure(s)  at  the  given  position  (offset). 

Parameters:  RastPort     RastPort  structure 

IText  IntuiText  structure(s) 

LeftOffset,  TopOffset 
Position 


Dec  Hex 

STRUCT 

URE  IntuiText, 0 

0   $0 

BYTE 

it_FrontPen 

foreground  color 

1   $1 

BYTE 

it_BackPen 

background  color 

2   $2 

BYTE 

it_DrawMode 

draw  mode 

3   $3 

BYTE 

it_KludgeFill00 

4   $4 

WORD 

it_LeftEdge 

relative  position 

6   $6 

WORD 

it_TopEdge 

8   $8 

APTR 

it_ITextFont 

TextAttr  structure 

12   $C 

APTR 

it_IText 

string 

16  $10 

APTR 

it_NextText 

next  IntuiText  structure 

20  $14 

LABEL 

it_SIZEOF 

AUTOFRONTPEN 

=  0 

AUTOBACKPEN 

=  1 

AUTODRAWMODE 

=  RP_JAM2 

AUTOLEFTEDGE 

=  6 

AUTOTOPEDGE 

=  3 

AUTOITEXTFONT 

=  0 

AUTONEXTTEXT 

=  0 
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Dec 

Hex 

STRUCTURE  Border, 0 

0 

SO 

WORD 

bd_LeftEdge 

2 

$2 

WORD 

bd_TopEdge 

4 

$4 

BYTE 

bd_FrontPen 

5 

$5 

BYTE 

bd_BackPen 

6 

$6 

BYTE 

bd_DrawMode 

7 

$7 

BYTE 

bd_Count 

8 

$8 

APTR 

bd_XY 

12 

$c 

APTR 

bd_Next  Bor de  r 

16 

$10 

LABEL 

bd_SIZEOF 

Dec 

Hex 

STRUCTURE  Image, 0 

0 

$0 

WORD 

ig_LeftEdge 

2 

$2 

WORD 

ig_TopEdge 

4 

$4 

WORD 

ig_Width 

6 

$6 

WORD 

ig_Height 

8 

$8 

WORD 

ig_Depth 

10 

$A 

APTR 

ig_ImageData 

14 

$E 

BYTE 

ig_PlanePick 

15 

$F 

BYTE 

ig_PlaneOnOf f 

16 

$10 

APTR 

ig_Next Image 

20 

$14 

LABEL 

ig_SIZEOF 

/relative  position 

; foreground  color 

; background  color 

;draw  mode 

; number  of  vectors 

/vector  table  (2  Words  each) 

;next  Border  structure 


relative  position 


Bitplanes 

destination  plane  to  be  used 
what  happens  with  the  others 
next  Image  structure 


6.  Other  Functions 


lAddClass 


Add  IClass  I 


Call:  AddClass(  Class   ) 

-684 (A6)      A0 

STRUCT  IClass  *Class 

Function:     Adds  an  IClass  from  MakeClass()  to  the  system  list. 

Parameters:  Class  Result  from  MakeClassQ 


|AUocRemember 


Allocate  and  remember  memory  block 


Call:  MemBlock  =  Al locRemember ( RememberKey ,  Size,  Flags) 

DO         -396 (A6)       A0  DO    Dl 

APTR   MemBlock 

STRUCT  Remember  **RememberKey 

ULONG  Size, Flags 


414 


3.1  The  Libraries  and  their  Functions 


Function:  Uses  AllocMem()  to  allocate  a  memory  block.  The  position 
and  size  of  the  reserved  block  is  held  in  a  RememberNode 
which  is  added  to  a  list  so  that  all  blocks  can  be  freed  with 
FreeRememberO  later. 

Parameters:  RememberKey 

Address  of  a  longword  that  contains  the 
address  of  the  first  RememberNode.  The  first 
time  the  function  is  called,  this  longword  must 
be  initialized  with  the  value  0. 

Size,Flags    Arguments  for  exec/AllocMem(Size,Flags). 

Result:  Address  of  the  allocated  memory  block  or  0. 

Example:      Allocate  and  free  memory  block(s): 


movea.l  _IntuiBase,a6 
clr.l   -(a7) 


; RememberKey =Null 


movea . 1  a7 , aO  ; RememberKey 

moveq   #rp_SIZEOF,dO  ; buffer  size 

move.l   #MEMF_CLEAR!MEMF_PUBLIC  ; memory  type 

jsr     _LVOAllocRemember  (a6)  .-allocate 

tst.l   dO  ;test 

beq     _Zerror  ;if  error 

;use  the  memory 

movea . 1  a7 , aO  ; RememberKey 

moveq   #bm_SIZEOF,dO  ;buffer  size 

move.l   #MEMF_CLEAR!MEMF_PUBLIC  ; memory  type 

jsr     _LVOAllocRemember (a6)  /allocate 

tst.l   dO  ;test 

beq     _Zerror  ;if  error 

;use  memory 


_Zerror 
movea.l  a7,a0 
moveq   #-l,dO 
jsr     _LVOFr eeRemember ( a 6 ) 
addq.l  #4,a7 


; RememberKey 
; clear  all 
;  free 
; restore  stack 
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|  CurrentTime  Get  the  current  time  | 

Call:  CurrentTime  (Seconds,   Micros) 

-84 (A6)  AO  Al 

APTR  Seconds, Micros 

Function:     Writes  the  current  time  to  the  longword  at  the  given 
address.  The  microsecond  value  is  not  exact. 

Parameters:  Seconds     Address  of  longword  for  seconds. 

Micros        Address  of  longword  for  microseconds. 

IDisposeObject  Delete  an  object! 

Call:  DisposeObject  (  Object   ) 

-642 (A6)  AO 

APTR  Object 

Function:     Deletes  the  given  object  including  its  data  and  subobjects. 

Parameters:  Object         Result  of  NewObject() 

|  DoubleClick     Compare  two  mouse  clicks  to  the  double  click  period  | 

\~>all:  IsDouble  =  Doubled  ick(StartSecs,  StartMicros,  CurrentSecs,  CurrentMicros) 

DO         -102  (A6)    DO        Dl  D2  D3 

BOOL  IsDouble 

ULONG  StartSecs,  StartMicros,  CurrentSecs.  CurrentMicros 

Function:      Compares  the  time  difference  between  two  mouse  clicks  to 
the  length  of  the  double-click  period. 

Parameters:  Start...         Time  of  the  first  mouse  click. 

Current...    Time  point  of  the  second  mouse  click. 

Result:  0  Time  points  too  far  apart  for  a  double-click. 
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Example:      Evaluate  mouse  click  for  IDCMP  messages  of  type 
MOUSEBUTTONS: 


**  IntuiMessage  in  al 

*  * 

**  Result:  dO  ><  0  for  double-click 


_MouseButtons 


movem . 1 

d2-d3/al/a6,-(a7) 

movea . 1 

_IntuiBase,a6 

movem . 1 

im_Seconds  (al)  ,  d2-d3 

lea 

_01dValues (pc) , aO 

movem . 1 

(aO),dO-dl 

movem . 1 

d2-d3, (aO) 

jsr 

JLVODoubl eClick(a6) 

tst.l 

dO 

movem . 1 

(a7)+,d2-d3/al/a6 

OldValues 

ds.l 

2 

IFreeClass 


Free  ICIassI 


Call:  success  =  FreeClass  (  ClassPtr  ) 

DO        -714 (A6)    AO 

STRUCT  IClass  *ClassPtr 

Function:      Attempts  to  free  the  result  of  a  MakeClass()  call. 

Parameters:  ClassPtr      IClass  structure 

Result:  0  IClass  could  not  be  freed. 

|  FreeRemember  Free  memory  and/or  Remember  structures  | 


Call:  FreeRemember (RememberKey,    ReallyForget) 

-408 (A6)  AO  DO 

STRUCT  Remember  **RememberKey 
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BOOL       Really Forget 

Function:  Frees  only  the  Remember  structures  (ReallyForget  =  0)  or 
the  associated  memory  blocks. 

Parameters:  RememberKey 

Address   of  the   longword   containing   the 
address  of  the  first  Remember  structure. 

ReallyForget 

Flag  that  indicates  whether  memory  blocks 
should  also  be  set  free. 

Example:  Allocate  several  memory  blocks  that  can  only  be  used  if  no 
errors  occur,  bit-planes  are  not  much  good  without  bit- 
maps, and  bit-maps  can't  be  used  without  RastPorts: 


movea.l  _IntuiBase,a6 
clr.l   -(a7) 
moveq   #-l,d2 


; RememberKey  =  0 

; error,  free  everything 


movea .1  a7 , aO 

moveq   #rp_SIZEOF,d0 

move . 1   #MEMF_CLEAR ! MEMF_PUBLIC , dl 

jsr     _LVOAllocRemember (a6) 

move .1  dO , d3 

beq . s    . Zerror 


; RememberKey 
;RastPort  size 
; memory  type 
;allocate 
;save  result 
; if  error 


movea.l  a7,a0  ; RememberKey 

moveq   #bm_SIZEOF,d0  ;BitMap  size 

move.l   #MEMF_CLEAR!MEMF_PUBLIC,dl  ;memory  type 

jsr     _LVOAllocRemember (a6)  /allocate 

move . 1  dO , d4  ; save  result 

beq.s    .Zerror  ;if  error 


moveq   #0,d2 


;no  errors,  just  free  Remember  structures 


. Zerror 
movea.l  a7,a0 
move .1  d2 , dO 

jsr     _LVOFreeRemember(a6) 
move .1  d2 , dO 


;  RememberKey 

/Remember  structures  or  everything 

;  free 

.•return  error  code 
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|  Get Attr  Get  object  attributes  | 

Call:  GetAttr(  AttrlD,  Object,  storagePtr  ) 

-654 (A6)  DO      AO      Al 

ULONG  result, AttrlD 
APTR  Obj  ect , StoragePtr 

Function:     Returns  the  attribute  values  for  the  given  object. 

Parameters:  AttrlD         Attribute  ID 

Object         Object  address 

StoragePtr  Address  of  longword  for  result. 

IGetDefPrefs  ~~      ~  Get  default  Preferences! 


Call:  Prefs  =  GetDefPrefs(Pref Buffer,    Size) 

DO  -126 (A6)  AO  DO 

STRUCT  Preferences   *Prefs, * Pre f Buffer 
WORD  Size 

Function:     Copies  the  default  Preferences  structure  to  a  buffer. 

Parameters:  PrefBuffer  Buffer  for  the  Preferences  structure. 

Size  Buffer  size 

Result:  Buffer  address 

1  GetPrefs  Get  the  current  Preferences  I 

Call:  Prefs  =  GetPrefs  (PrefBuffer,    Size) 

DO  -132 (A6)    AO  DO 

STRUCT  Preferences   *Prefs, *Pref Buffer 
WORD       Size 

Function:     Copies  the  current  Preferences  structure  to  a  buffer. 
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Parameters:  PrefBuffer  Buffer  for  the  Preferences  structure. 

Size  Buffer  size 

Result:  Buffer  address 

ILocklBase  Lock  IntuitionBasel 

Call:  Lock  =  LocklBase(LockNumber) 

DO  -414 (A6)      DO 

ULONG  Lock,LockNumber 

Function:  Locks  one  or  more  Intuition  functions.  This  is  required  for 
operations  such  as  dynamic  entries  in  the  IntuiBase 
structure. 

Parameters:  LockNumber 

Number  of  the  internal  SignalSemaphore  or  0 
(almost  all  SSs). 

Result:  Number  of  the  allocated  SignalSemaphore  or  0  (almost  all). 

IMakeClass  Define  object  class | 

Call:  IClass  n   MakeClassI  ClassID,  SuperClassID,  SuperClassPtr,  Instances! ze,  Flags) 

DO       -678  (A6)   AO       M  A2  DO  Dl 

STRUCT  IClass  *IClass,*SuperClassPtr 
APTR   ClassID, SuperClassID 
uword  Instances!  ze 
ULONG  Flags 

Function:  Defines  a  new  object  class.  The  object  class  must  be 
registered  with  Commodore. 

Parameters:  ClassID       PublicClass  name  or  0  (PrivateClass) 

SuperClassID 

Superclass  name  or  0  (PrivateClass) 
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SuperClassPtr 

Private  Superclass  address 

InstanceSize 

Object  data  structure  size 

Flags  0 

Result:  IClass  or  0 

INewObjectA  Create  a  new  object) 

Call:  Object  =  NewObjectA(  class,  classID,  tagList  ) 

DO       -636 (A6)     AO     Al       A2 

APTR   Object, classID 
STRUCT  IClass  *class 
STRUCT  Tagltem  *tagList 

Function:     Create  a  Boopsi  class  object  (Boopsi  =  Basic  object- 
oriented  Programming  System  for  Intuition). 

Parameters:  class  BoopsiClass  from  MakeClass() 

classID       Name  if  class=0 

tagList       Tagltems  for  the  object 

Result:  Object  that  may  be  used,  for  example,  as  a  gadget  or  image. 

|  Next  Object  Get  the  next  object! 

Call:  Object  =  NextObject    (   objectPtrPtr   ) 

DO  -666 (A6)  AO 

APTR  Object, objectPtrPtr 

Function:     Gets     the     next    object    entered     in     a    list    by 
OM_ADDMEMBER. 

Parameters:  objectPtrPtr  Address  of  the  list  or  an  object. 
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Result:  Object  or  0 

|  Pointlnlmage  Checks  to  see  if  a  point  is  in  an  Image  | 

Call:  DoesContain  =  Pointlnlmage (   Point,    Image   ) 

DO  -624 (A6)  DO  AO 

BOOL  DoesContain 

STRUCT  Point   Point    (LONG) 

STRUCT  Image   * Image 

Function:     Checks  to  see  if  a  point  at  the  given  coordinates  in  the 
Image  is  set  (for  BOOLMASK,  etc.). 

Parameters:  Point  X«16!Y  (packed  coordinates) 

Image  Image  or  Customlmage 

Result:  0  Point  not  set 

|  RemoveClass  Remove  Boopsi  class  from  system  list  I 

Call:  RemoveClass  (   classPtr   ) 

-708 (A6)  AO 

STRUCT  iciass  *classPtr 

Function:      Removes  an  IClass  from  the  system  list. 

Parameters:  ClassPtr      Result  from  MakeClass() 

|  SetAttrsA  Set  object  attributes! 

Call:  result  =  SetAttrsA (  object,  TagList  ) 

DO       -648 (A6)      AO      Al 

APTR   Object 

STRUCT  Tagltem  *TagList 

ULONG  result 

Function:     Defines  a  set  of  attributes  for  a  Boopsi  object. 
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Parameters:  Object         Object 

TagList       Tagltem  field 

Result:  Not  0  if  the  object  is  a  gadget  and  should  be  refreshed  in 

order  for  the  new  attributes  to  be  displayed. 

|  SetPrefs  Change  the  Preferences  settings  | 

Call:  Prefs  =  SetPrefs (PrefBuffer,    Size,    Inform) 

DO  -324 (A6)    AO  DO  Dl 

STRUCT  Preferences   *Prefs,    *Pref Buffer 
LONG       Size 
BOOL        Inform 

Function:  Changes  the  default  Preference  settings  and  informs 
(optional)  all  windows.  The  Preferences  structure  no  longer 
contains  all  the  defaults.  This  routine  should  never  be  used. 

Parameters:  PrefBuffer  Custom  settings 

Size  Size  of  custom  structure 

Inform        Boolean  -  Inform  windows 
Result:  PrefBuffer 

lUnlocklBase  Free  IntuitionBasej 


Call:  unlocklBase(Lock) 

-420 (A6)  AO 

ULONG  Lock 

Function:     Frees  the  SignalSemaphore(s)  locked  with  LockIBase(). 
Parameters:  Lock  SignalSemaphore  number  or  0  (almost  all). 


Dec  Hex  STRUCTURE  Remember, 0 
0   $0  APTR   rm_NextRemember 
4  $4  LONG   rm_RememberSize 
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8   $8  APTR   rm_Memory 
12   $C  LABEL   rm_SIZEOF 

FILENAME_SIZE  =30  ;file  name  size 

POINTERSIZE   =  (1+16+1) *2   ;mouse  pointer  size 
TOPAZ_EIGHTY   =  8 
TOPAZ_SIXTY    =  9 


Dec  Hex  STRUCTURE  Preferences, 0  ; Anachronism! 

0  $0  BYTE    pf_FontHeight 

1  $1  BYTE   pf_PrinterPort 

2  $2  WORD    pf_BaudRate 

4   $4  STRUCT  pf_KeyRptSpeed,TV_SIZE 
12   $C  STRUCT  pf_KeyRptDelay,TV_SIZE 
STRUCT  pf_DoubleClick,TV_SIZE 
STRUCT  pf_PointerMatrix, POINTERSIZE*2 
BYTE    pf_XOffset 
BYTE    pf_YOffset 
WORD   pf_colorl7 
WORD    pf_colorl8 
WORD    pf_colorl9 
WORD   pf_PointerTicks 
WORD   pf_color0 
WORD   pf_colorl 
WORD   pf_color2 
WORD   pf_color3 
BYTE    pf_ViewXOffset 
BYTE   pf_ViewYOffset 
WORD   pf_ViewInitX 
WORD   pf_ViewInitY 
BOOL   EnableCLI 
WORD   pf_PrinterType 


20  $14 
28  $1C 

64  $40 

65  $41 

66  $42 
68  $44 
70  $46 
72  $48 
74  $4A 
76  $4C 
78  $4E 
80  $50 

82  $52 

83  $53 

84  $54 
86  $56 
88  $58 
90  $5A 
92  $5C 

122  $7A 
124  $7C 
126  $7E 
128  $80 
130  $82 
132  $84 
134  $86 
136  $88 
138  $8A 
140  $8C 
142  $8E 
144  $90 

146  $92 

147  $93 

148  $94 


STRUCT  pf_PrinterFilename, FILENAME_SIZE 

WORD  pf_PrintPitch 

WORD  pf_PrintQuality 

WORD  pf_PrintSpacing 

WORD  pf_PrintLeftMargin 

WORD  pf_PrintRightMargin 

WORD  pf_PrintImage 

WORD  pf_PrintAspect 

WORD  pf_PrintShade 

WORD  pf_PrintThreshold 

WORD  pf_PaperSize 

WORD  pf_PaperLength 

WORD  pf_PaperType 

BYTE  pf_SerRWBits 

BYTE  pf_SerStopBuf 

BYTE  pf_SerParShk 
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149 

$95 

BYTE 

150 

$96 

STRUCT 

180 

$B4 

BYTE 

181 

$B5 

BYTE 

182 

$B6 

UWORD 

184 

$B8 

WORD 

186 

$BA 

UWORD 

188 

$BC 

UBYTE 

189 

$BD 

UBYTE 

190 

$BE 

UWORD 

192 

$C0 

UWORD 

194 

$C2 

UBYTE 

195 

$C3 

UBYTE 

196 

$C4 

LABEL 

pf_LaceWB 

pf_WorkName, FILENAME_SIZE 

pf _RowS  i  zeChange 

pf_ColumnSizeChange 

pf_PrintFlags 

pf_PrintMaxWidth 

pf _Pr intMaxHe  ight 

pf_PrintDensity 

pf_PrintXOffset 

pf_wb_Width 

pf_wb_Height 

pf_wb_Depth 

pf_ext_size 

pf_SIZEOF 


LACEWB 


PARALLEL_PRINTER 

= 

0 

SERIAL_PRINTER 

= 

1 

BAUD_110 

= 

0 

BAUD_300 

= 

1 

BAUD_1200 

= 

2 

BAUD_2400 

= 

3 

BAUD_4800 

= 

4 

BAUD_9600 

= 

5 

BAUD_19200 

= 

6 

BAUD_MIDI 

= 

7 

FANFOLD 

= 

0 

SINGLE 

= 

$80 

PICA 

= 

0 

ELITE 

= 

$400 

FINE 

= 

$800 

DRAFT 

= 

0 

LETTER 

= 

$100 

SIX_LPI 

= 

0 

EIGHT_LPI 

= 

$200 

IMAGE_POSITIVE 

= 

0 

IMAGE_NEGATIVE 

= 

1 

ASPECT_HORIZ 

= 

0 

ASPECT_VERT 

= 

1 

SHADE_BW 

= 

0 

SHADE_GREYSCALE 

= 

1 

SHADE_COLOR 

= 

2 

US_LETTER 

= 

0 

US_LEGAL 

= 

$10 

N_TRACTOR 

= 

$20 
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W_TRACTOR 

= 

$30 

CUSTOM 

= 

$40 

CUSTOM_NAME 

= 

0 

ALPHA_P_101 

= 

1 

BROTHER_15XL 

= 

2 

CBM_MPS10  00 

= 

3 

DIAB_630 

= 

4 

DIAB_ADV_D25 

= 

5 

DIAB_C_150 

= 

6 

EPSON 

= 

7 

EPSON_JX_80 

= 

8 

OKIMATE_20 

= 

9 

QUME_LP_20 

= 

$A 

HP_LASERJET 

= 

$B 

HP_LASERJET_PLUS  = 

$c 

SBUF_512 

= 

0 

SBUF_1024 

= 

1 

SBUF_2048 

= 

2 

SBUF_4096 

= 

3 

SBUF_8000 

= 

4 

SBUF_16000 

= 

5 

SREAD_BITS 

=  $F0 

;  Pf. 

.SerRWBits 

SWRITE_BITS 

=   $F 

SSTOP_BITS     =  $F0  ;  pf_SerStopBuf 
SBUFSIZE_BITS  =   $F 


SPARITY_BITS 
SHSHAKE_BITS 


$F0  ;  pf_SerParShk 
$F 


SPARITY_NONE 
SPARITY_EVEN 
SPARITY_ODD 


SHSHAKE_XON 
SHSHAKE_RTS 
SHSHAKE_NONE 


CORRECT_RED 
CORRECT_GREEN 
CORRECT_BLUE 
CENTER_IMAGE 


IGNORE_DIMENSIONS  =  0 
BOUNDED_DIMENSIONS  =  $10 
ABSOLUTE_DIMENSIONS  =  $20 
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PIXEL_DIMENSIONS 
MULTI PLY_DIMENS IONS 


$40 
$80 


INTEGER_SCALING 


=  $100 


ORDERED_DITHERING  =  0 
HALFTONE_DITHERING  =  $200 
FLOYD_DITHERING      =  $400 


ANTI_ALIAS 
GREY_SCALE2 


=  $800 

=$1000  ;for  A2024  monitor 


CORRECT_RGB_MASK     =  ( CORRECT_RED+CORRECT_GREEN+CORRECT_BLUE ) 
DIMENSIONS_MASK 

(BOUNDED_DIMENSIONS+ABSOLUTE_DIMENSIONS+PIXEL_DIMENSIONS+MULTIPLY_DIMENSIONS) 
DITHERING_MASK       =  (HALFTONE_DITHERING+FLOYD_DITHERING) 


Dec  Hex  STRUCTURE  ICLASS,0 

0   $0  STRUCT  cl_Dispatcher,h_SIZEOF 


20 

$14  ULONG 

cl_Reserved 

24 

$18  APTR 

cl_Super 

28 

$1C  APTR 

cl_ID 

32 

$20  UWORD 

cl_InstOf fset 

34 

$22  UWORD 

cl_InstSize 

36 

$24  ULONG 

cl_UserData 

40 

$28  ULONG 

c l_Subclas  sCount 

44 

$2C  ULONG 

cl_ObjectCount 

48 

$30  ULONG 

cl_Flags 

;  Hook 
;0 

; string 


;User  data  for  the  Class 
; number  of  subclasses 
; number  of  objects 


CLB_INLIST  =  0,  CLF_INLIST  =  1  ;Class  in  PublicClassList 

Dec  Hex  STRUCTURE  _Object,0 
0   $0  STRUCT  o_Node,MLN_SIZE 
8   $8  APTR   o_Class 
12   $C  LABEL  _object_SIZEOF 

Dec  Hex  STRUCTURE  Msg,0 

0   $0  ULONG  msg_MethodID  ;data  to  follow 
4   $4  . . .  ; according  to  ID  (see  below) 

OM_NEW  =  $101  /parameter  is  really  a  Class 

OM_DISPOSE  =  $102  ; self -deleting  (no  parameters) 

OM_SET  =  $103  ;set  attributes  (list) 

OM_GET  =  $104  ;read  attributes 

OM_ADDTAIL  =  $105  ;add  self  to  list 

OM_REMOVE  =  $106  .-remove  self  from  list  (no  parameters) 

OM_NOTIFY  =  $107  ; notify  self 

OM_UPDATE  =  $108  ;NotifyMsg 
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OM_ADDMEMBER  =  $109  ; 
OM_REMMEMBER  =  $10A  ; 

Dec  Hex  STRUCTURE  opSet,4  ;OM_NEW,  OM_SET 

4   $4  APTR   ops_AttrList  ;new  attributes 
8   $8  APTR   ops_GInfo     ;0  for  0M_NEW 

Dec  Hex  STRUCTURE  opUpdate,4  ;0M_UPDATE 

4   $4  APTR   opu_AttrList  /attributes 
8   $8  APTR   opu_GInfo 
12   $C  ULONG  opu_Flags 

OPUB_INTERIM  =  0,  OPUF_INTERIM  =  1 

Dec  Hex  STRUCTURE  opGet , 4  ; OM_GET 


$4  ULONG 
$8  APTR 


°Pg_AttrID 
opg_Storage 


Dec  Hex  STRUCTURE  opAddTail,4  ;OM_ADDTAIL 

4   $4  APTR    opat_List 
Dec  Hex  STRUCTURE  opMember,4  ;OM_. . .MEMBER 

4   $4  APTR   opam_Object 


GA_Dummy 

GA_LEFT 

GA_RELRIGHT 

GA_TOP 

GA_RELBOTTOM 

GA_WIDTH 

GA_RELWIDTH 

GA_HEIGHT 

GA_RELHEIGHT 

GA_TEXT 

GA_IMAGE 

GA_BORDER 

GA_SELECTRENDER 

GA_H1GHLIGHT 

GA_DISABLED 

GA_GZZGADGET 

GA_ID 

GA_USERDATA 

GA_SPECIALINFO 


=  TAG_USER+$30000 
=  TAG_USER+$30001 
=  TAG_USER+$30002 
=  TAG_USER+$30003 
=  TAG_USER+$30004 
=  TAG_USER+$30005 
=  TAG_USER+$30006 
=  TAG_USER+$30007 
=  TAG_USER+$30008 
=  TAG_USER+$30009 
=  TAG_USER+$3000A 
=  TAG_USER+$3000B 
=  TAG_USER+$3000C 
=  TAG_USER+$3000D 
=  TAG_USER+$3000E 
=  TAG_USER+$3000F 
=  TAG_USER+$30010 
=  TAG_USER+$30011 
=  TAG_USER+$30012 


;Gadget  attributes 
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GA_SELECTED 

GA_ENDGADGET 

GA_IMMEDIATE 

GA_RELVERIFY 

GA_FOLLOWMOUSE 

GA_RIGHTBORDER 

GA_LEFTBORDER 

GA_TOPBORDER 

GA_BOTTOMBORDER 

GAJTOGGLESELECT 

GA_SYSGADGET 

GA_SYSGTYPE 

GA_PREVIOUS 

GA_NEXT 

GA_DRAWINFO 

GA_INTUITEXT 

GA_LABELIMAGE 


=  TAG_USER+$30013 
=  TAG_USER+$30014 
=  TAG_USER+$3  0015 
=  TAG_USER+$30016 
=  TAG_USER+$30017 
=  TAG_USER+$30018 
=  TAG_USER+$30019 
=  TAG_USER+$3001A 
=  TAG_USER+$3001B 
=  TAG_USER+$3001C 
=  TAG_USER+$3001D 
=  TAG_USER+$3001E 
=  TAG_USER+$3001F 
=  TAG_USER+$30020 
=  TAG_USER+$30021 
=  TAG_USER+$30022 
=  TAG_USER+$30023 


PGA_Dummy 

PGA_FREEDOM 

PGA_BORDERLESS 

PGA_HORIZPOT 

PGA_HORIZBODY 

PGA_VERTPOT 

PGA_VERTBODY 

PGA_TOTAL 

PGA_VISIBLE 

PGA_TOP 


=  TAG_USER+$31000  ;PropGadget  attributes 

=  TAG_USER+$31001 

=  TAG_USER+$31002 

=  TAG_USER+$31003 

=  TAG_USER+$31004 

=  TAG_USER+$31005 

=  TAG_USER+$31006 

=  TAG_USER+$31007 

=  TAG_USER+$31008 

=  TAG_USER+$31009 


STRINGA_Dummy 

STRINGA_MaxChars 

STRINGA_Buffer 

STRINGA_UndoBuffer 

STRINGA_WorkBuffer 

STRINGAJBufferPos 

STRINGA_DispPos 

STRINGA_AltKeyMap 

STRINGA_Font 

STRINGA_Pens 

STRINGA_Act  ivePens 

STRINGA_EditHook 

STRINGA_EditModes 

STRINGA_ReplaceMode 

STRINGA_FixedFieldMode 

STRINGA_NoFilterMode 

STRINGA_Just  i  f  icat  ion 

STRINGA_LongVal 

STRINGAJTextVal 


TAG_USER+$32000 
TAG_USER+$32001 
TAG_USER+$32002 
TAG_USER+$32003 
TAG_USER+$32004 
TAG_USER+$32005 
TAG_USER+$32006 
TAG_USER+$32007 
TAG_USER+$32008 
TAG_USER+$32009 
TAG_USER+$3200A 
TAG_USER+$3200B 
TAG_USER+$3200C 
TAG_USER+$3200D 
TAG_USER+$3200E 
TAG_USER+$3200F 
TAG_USER+ $32010 
TAG_USER+$32011 
TAG_USER+$32012 


;StringGadget  attributes 
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SG_DEFAULTMAXCHARS   =  128  ; default  buffer  length 

LAYOUTA_Dummy       =  TAG_USER+$38000  /Layout 

LAYOUTA_LAYOUTOBJ    =  $38001 

LAYOUTA_SPACING      =  $38002 

LAYOUTA_ORIENTATION  =  $38003 

LORIENT_NONE        =  0  ,-orientation 
LORIENT_HORIZ        =  1 
LORIENT_VERT         =  2 

GM_HITTEST  =  0  ; send  Hook  commands  to  GMR_GADGETHIT 

GM_RENDER  =  1  ;draw  self 

GM_GOACTIVE  =  2  ,-Gadget  activated 

GM_HANDLEINPUT  =  3  /process  input 

GM_GOINACTIVE  =  4  ,-Gadget  inactivated 

Dec  Hex  STRUCTURE  MsgHeader,  0  ,- again  for  structures 
4   $4  ULONG    MethodID 
8   $8  LABEL    methodid_SIZEOF 

Dec  Hex  STRUCTURE  gpHitTest,methodid_SIZEOF 
4   $4  APTR   gpht_GInfo 
8   $8  WORD   gpht_MouseX 
10   $A  WORD   gpht_MouseY 

GMR_GADGETHIT  =  4  ;not  hit  =  0 

Dec  Hex  STRUCTURE  gpRender,methodid_SIZEOF 
4   $4  APTR   gpr_GInfo    ;GadgetContext 
8  $8  APTR   gpr_RPort 
12   $C  LONG   gpr_Redraw 

GREDRAW_UPDATE   =  2    ,- update  with  new  attributes 
GREDRAW_REDRAW   =  1    ; refresh 
GREDRAW_TOGGLE   =  0    ; toggle 

Dec  Hex  STRUCTURE  gpInput,methodid_SIZEOF  ;also  GM_GOACTIVE 
4   $4  APTR   gpi_GInfo 
gpi_IEvent 
gpi_Termination 
gpi_MouseX 
gpi_MouseY 

Dec  Hex  STRUCTURE  gpGoInactive,methodid_SIZEOF 
4   $4  APTR    gpgi_GInfo 
8   $8  ULONG   gpgi_Abort  ;V37  and  up! 
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8 

$8 

APTR 

12 

$c 

APTR 

16 

$10 

WORD 

18 

$12 

WORD 
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GMR_MEACTIVE  =  0 
GMR_NOREUSE  =  2 
GMR_REUSE  =  4 
GMRVERIFY    =  8 


GMRB_NOREUSE  =  1, 

GMRF_NOREUSE  =  2 

GMRB_REUSE    =  2, 

GMRF_REUSE    =  4 

GMRB_VERIFY   =  3, 

GMRF_VERIFY   =  8 

ICM_SETLOOP  =  $402 
ICM_CLEARLOOP  =  $403 
ICM_CHECKLOOP  =  $404 


ICA_Dummy 
ICA_TARGET 
ICA_MAP 
ICSPECIAL_CODE 


$40000 
ICA_Dummy+l 
ICA_Dummy+2 
ICA_Dummy+3 


ICTARGET_IDCMP  =  -1  ;$ffffffff 


CUSTOMIMAGEDEPTH  =  -1  ; depth  for  CustomGadgets 


IMAGE_ATTRIBUTES 

IA_LEFT 

IA_TOP 

IA_WIDTH 

IA_HEIGHT 

IA_FGPEN 

IA_BGPEN 

IA_DATA 

IA_LINEWIDTH 

IA_PENS 

IA_RESOLUTION 

IA_APATTERN 

IA_APATSIZE 

IA_MODE 

IA_FONT 

IA_OUTLINE 

IA_RECESSED 

IA_DOUBLEEMBOSS 

IA_EDGESONLY 


TAG_USER+$20000 
IMAGE_ATTRIBUTES+  $  0 1 
IMAGE_ATTRIBUTES+$02 
IMAGE_ATTRIBUTES+ $0  3 
IMAGE_ATTRI BUTES+ $  0  4 
IMAGE_ATTRIBUTES+$05 
IMAGE_ATTRIBUTES+$06 
IMAGE_ATTRIBUTES+  $  0  7 
IMAGE_ATTRIBUTES+  $  0  8 
IMAGE_ATTRIBUTES+  $  0E 
IMAGE_ATTRIBUTES+ $  OF 
IMAGE_ATTRIBUTES+  $  0 1 0 
IMAGE_ATTRIBUTES+  $  0 1 1 
IMAGE_ATTR I BUTES + $ 0 1 2 
IMAGE_ATTRIBUTES+$013 
IMAGE_ATTRIBUTES+  $  0 1 4 
IMAGE_ATTRIBUTES+  $  0 1 5 
IMAGE_ATTRIBUTES+ $ 0 1 6 
IMAGE_ATTRI BUTES+ $ 0 17 


SYSIA_Size     =  IMAGE_ATTRIBUTES+$0B  ; system  IClass 
SYSIA_Depth    =  IMAGE_ATTRIBUTES+$0C 
SYSIA_Which    =  IMAGE_ATTRIBOTES+$0D 
SYSIA_DrawInfo  =  IMAGE_ATTRIBUTES+$018 
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SYSIA_Pens 

IA_SHADOWPEN 

IAHIGHLIGHTPEN 


IA_PENS 

IMAGE_ATTRIBUTES+ $  0  9 
IMAGE_ATTRIBUTES+$OA 


SYSISIZE_MEDRES  =  0 
SYSISIZE_LOWRES  =  1 
SYSISIZEHIRES   =  2 


DEPTHIMAGE   = 

0  ; SYSIA_Witch  values 

ZOOMIMAGE 

1 

SIZEIMAGE 

2 

CLOSEIMAGE   = 

3 

SDEPTHIMAGE  = 

5 

LEFTIMAGE 

$A 

UPIMAGE 

$B 

RIGHTIMAGE   = 

$c 

DOWNIMAGE 

$D 

CHECKIMAGE   = 

$E 

MXIMAGE 

$F 

IM_DRAW 

=  $202 

;draw  self 

IM_HITTEST 

=  $203 

; TRUE=hit 

IM_ERASE 

=  $204 

; delete  self 

IM_MOVE 

=  $205 

; redraw 

IM_DRAWFRAME 

=  $206 

;draw  within  Box 

IM_FRAMEBOX 

=  $207 

IM_HITFRAME 

=  $208 

IM_ERASEFRAME 

=  $209 

IDS_NORMAL 

=  0 

IDS_SELECTED 

=  1  ; active 

IDS_DISABLED 

=  2  ; cannot  be  selected 

IDS_BUSY 

=  3 

IDS_INDETERMINATE 

=  4 

IDS_INACTIVENORMAL 

=  5  ; within  window  bord< 

IDS_INACTIVESELECTED 

=  6  ; 

IDS_INACTIVEDISABLED 

=  7  ; 

IDS_INDETERMINANT 


=  IDS_INDETERMINATE 


Dec  Hex  STRUCTURE  impFrameBox, 4 


4 

$4  APTR 

imp  f  _Cont  en  t  s  Box 

8 

$8  APTR 

impf_FrameBox 

12 

$C  APTR 

impf_DrInfo 

16 

$10  LONG 

impf_FrameFlags 

FRAMEB_SPECIFY 


0,  FRAMEF_SPECIFY   =  1 


Dec  Hex  STRUCTURE  impDraw, 4 
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4 

$4  APTR 

impd_RPort 

8 

$8  WORD 

impd_OffsetX 

10 

$A  WORD 

impd_OffsetY 

12 

$C  ULONG 

impd_State 

16 

$10  APTR 

impd_DrInfo 

20 

$14  WORD 

impd_DimensionsWidth 

22 

$16  WORD 

impd_DimensionsHeight 

tec 

Hex  STRUCTURE  impErase , 4 

4 

$4  APTR 

impe_RPort 

8 

$8  WORD 

impe_Of fsetX 

10 

$A  WORD 

impe_Of fsetY 

12 

$C  WORD 

impe_DimensionsWidth 

14 

$E  WORD 

impe_DimensionsHeight 

tec 

Hex  STRUCTURE  impHitTest,4 

4 

$4  WORD 

imph_PointX 

6 

$6  WORD 

imph_PointY 

8 

$8  WORD 

imph_Dimens  ionsWidth 

10 

$A  WORD 

imph_Dimens  ionsHe  ight 

3.1.12        The  Layers  Library 


The  "layers.library"  is  responsible  for  the  complex  Clipping  and  Refresh 
of  overlapping  software  levels.  The  base  address  of  the  function  is 
expected  in  A6. 


Functions  of  the  Layers  Library 

BeginUpdate 

BehindLayer 

CreateBehindHookLayer 

CreateBehindLayer 

CreateUpfrontHookLayer 

CreateUpfrontLayer 

DeleteLayer 

DisposeLayerlnfo 

EndUpdate 

InstallClipRegion 

InstallLayerHook 

LockLayer 

LockLayerlnfo 


LockLayers 

MoveLayer 

MoveLayerlnFrontOf 

MoveSizeLayer 

NewLayerlnfo 

ScrollLayer 

SizeLayer 

SwapBitsRastPortClipRect 

UnlockLayer 

UnlockLayerlnfo 

UnlockLayers 

UpfrontLayer 
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Description  of  the  routines 

IBeginUpdate  Begin  layer  update  | 

Call:  result  =  BeginUpdate  (  1   ) 

dO  -78 (A6)  aO 

LONG       result 
STRUCT  Layer  *1 

Function:     Converts  the  DamageList  to  a  ClipRectList  and  adds  it  to 
the  layer. 

Parameters:  1  Layer 

Result :  0  Error  (EndUpdate(l,0)  call) 

|  BehindLayer  Put  layer  in  the  background | 

Call:  result  =  BehindLayer  (   1   ) 

dO  -54 (A6)  al 

LONG       result 
STRUCT  Layer  *1 

Function:     Moves  the  given  layer  behind  all  other  layers. 

Parameters:  1  Layer 

Result:         0  Error 

ICreateBehindHookLayer  Create  layer  with  backfill  hookl 

Cflll."  result  »  CreateBeMndHookLayer(ll,lm,xO,yO,xl,yl, flags, hook, fcm2) 

do  -192  (A6)  aO  al  dO  dl  d2  d3  d4         a3       a2 

STRUCT  Layer  'Result:        STRUCT  Layer_Info  *11 
STRUCT  BitMap  *hm,*bm2 
LONG      xO,  yO,  xl,  yl,  flags 
STRUCT  Hook  *hook 
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Function:      Creates  a  new  layer  in  the  background  and  installs  a 
backfill  hook. 


Parameters: 

H 

Layerlnfo 

bm 

Screen  bit-map 

xO,yO 

Upper  left  corner 

xl.yl 

Lower  right  corner 

flags 

Layer  type 

hook 

BackFill  hook 

bm2 

SuperBitMap  or  0 

Result: 

Layer  or 

0 

ICreateBehindLayer  Create  layer  in  background! 

Call:  result  =  CreateBehindLayer (Ii,bm,x0,y0,xl,yl,  flags,  bm2) 

dO       -42 (A6)  aO  al  dO  dl  d2  d3  d4    a2 

STRUCT  Layer  *result 
STRUCT  Layer_Info  *li 
STRUCT  BitMap  *bm,*bm2 
LONG   xO,yO,xl,yl, flags 

Function:     Creates  a  new  layer  behind  all  other  layers. 
Parameters:  H  Layerlnfo 

bm  Screen  bit-map 

xO.yO         Upper  left  corner 

xl.yl  Lower  right  corner 

flags  Layer  type 
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bm2  SuperBitMap  or  0 

Result:  Layer  or  0 

ICreateUpfrontHookLayer  Create  foreground  layer  with  hook| 

KsCLlll  result  =  CreateUpfrontHookLayer(li,bm,xO,yO,xl,yl,  flags,  hook,  bm2) 

dO  -186 (A6)  aO  al  do  dl  d2  63  d4        a3       a2 

STRUCT  Layer  "result 
STRUCT  Layer_Info  *li 
STRUCT  BitMap  *ta,*bm2 
LONG      xO,yO,xl,yl,  flags 
STRUCT  Hook  *hook 

Function:     Creates  a  new  layer  in  the  foreground  and  installs  a  backfill 
hook. 


Parameters:  H 

Layerlnfo 

bm 

Screen  bit-map 

xO,yO 

Upper  left  corner 

xl,yl 

Lower  right  corner 

flags 

Layer  type 

hook 

BackFill  hook 

bm2 

SuperBitMap  or  0 

Result:          Layer  or 

0 

ICreateUpfrontLayer  Create  a  foreground  layer  | 

Call:  result  =  CreateUpfrontLayer(li,bm,xO,yO,xl,yl,  flags, bm2) 

dO  -36 (A6)  aO  al   dO  dl   d2  d3   d4  a2 

STRUCT  Layer  *result 
STRUCT  Layer_Info  *li 
STRUCT  BitMap  *bm, *bm2 

LONG   xO,yO,xl,yl, flags 
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Function:      Creates  a  new  layer  in  the  foreground. 
Parameters:  li  Layerlnfo 

bm  Screen  bit-map 

xO,yO  Upper  left  corner 

xl.yl  Lower  right  corner 

flags  Layer  type 

bm2  SuperBitMap  or  0 

Result:  Layer  or  0 

IDeleteLayer  Free  a  layer  | 

Call:  result  =  DeleteLayer(   1   ) 

dO  -90 (A6)  al 

LONG       result 
STRUCT  Layer   *1 

Function:      Frees  the  given  layer  and  its  memory  blocks. 

Parameters:  1  Layer 

Result:  0  Error 

|DisposeLayerInfo  Free  the  Layerlnfo! 

Call:  DisposeLayerInfo(   li   ) 

-150 (A6)  a0 

STRUCT  Layer_Info  *li 

Function:     Free  Layerlnfo  and  its  memory. 

Parameters:  li  Layerlnfo 
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|EndUpdate  End  update  and  normalize  clipping | 

Call:  Endupdate(   1,    flag   ) 

-84 (A6)  aO   dO 

STRUCT  Layer  *1 
UWORD     flag 

Function:      Return  normal  ClipRects  to  the  layer. 

Parameters:  1  Layer 

flag  TRUE:  Update  completely  ended. 

llnstallClipRegion  Install  clipping | 

Call:  oldclipregion  =  InstallClipRegion (  1,  region  ) 

dO  -174 (A6)  aO  al 

STRUCT  Region  *oldclipregion, *region 
STRUCT  Layer  *1 

Function:      Installs  a  new  clipping  region  in  layer. 
Parameters:  1  Layer 

region         New  ClipRegion 
Result:  Previous  ClipRegion  or  0 

InstallLayerHook  Install  backfill  hookj 


Call:  oldhook  =  InstallLayerHook (   layer,   hook  ) 

dO  -198 (A6)  aO  al 

STRUCT  Hook  *oldhook,*hook 
STRUCT  Layer   * layer 

Function:     Installs  a  new  backfill  hook  in  a  layer. 

Parameters:  layer  Layer 
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hook  New  backfill  hook 

Result:  Previous  backfill  hook 


ILockLayer  Lock  layer | 

Call:  LockLayer(   1   ) 

-96 (A6)  al 

STRUCT  Layer   *1 

Function:      Lock  a  layer  from  other  programs. 

Parameters:  1  Layer 

ILockLayerlnfo  Lock  Layerliifol 

Call:  LockLayerlnf o  (   li   ) 

-120 (A6)  aO 

STRUCT  Layerlnfo  *li 

Function:      Lock  Layerlnfo  from  other  programs. 

Parameters:  i  Layerlnfo 

ILockLayers  Lock  all  layers  of  a  Layerlnfol 

Call:  LockLayers  (   li   ) 

-108 (A6)  aO 

STRUCT  Layerlnfo  *li 

Function:     Locks  an  entire  layer  system  from  other  programs. 

Parameters:  H  Layerlnfo 

IMoveLayer  Move  a  layer  | 

Call:  result  =  MoveLayer(   1,    dx,   dy   ) 

dO  -60 (A6)  al  dO     dl 
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LONG   result, dx,dy 
STRUCT  Layer  *1 

Function:     Move  a  layer  relative  to  its  current  position. 

Parameters:  1  Layer 

dx  Relative  X  position 

dy  Relative  Y  position 

Result:  0  Error 

IMoveLayerlnFrontOf  Move  layer  in  front  of  another  layer | 

Call:  result  =   MoveLayerlnFrontOf  (  layertomove,  targetlayer  ) 

dO       -168 (A6)  aO  al 

LONG   result 

STRUCT  Layer  * layertomove, 'targetlayer 

Function:      Moves  one  layer  in  front  of  another. 

Parameters:  layertomove 

Layer  to  move  in  front  of  targetlayer. 

targetlayer  Layer  that  layertomove  will  overlay. 

Result:  0  Error 

IMoveSizeLayer  Change  layer  size  and  position! 

Call:  result  =  MoveSizeLayer  (  layer,  dx,  dy,  dw,  dh  ) 

dO       -180 (A6)       aO     dO   dl   d2   d3 

LONG   result, dx,dy,dw, dh 
STRUCT  Layer  * layer 

Function:     Move  upper  left  and  lower  right  corners. 
Parameters:  layer  Layer 
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dx.dy  Relative  position 

dw,dy  Relative  size 

Result:  0  Error 

INewLayerlnfo 


Call:  result  =  NewLayerlnf  o  ( ) 

dO       -144 (A6) 

STRUCT  Layerlnfo  *result 

Function:     Creates  a  new  Layerlnfo  structure. 

Result:  Layerlnfo  or  0 

IScrollLaver 


Get  Layerlnfo  | 


Scroll  layer  contents] 


Call:  ScrollLayer  (   1,    dx,    dy   ) 

-72 (A6)  al  dO     dl 

STRUCT  Layer  *1 
LONG   dx,dy 

Function:      Scrolls  the  contents  of  a  layer. 

Parameters:  1  Layer 

dx  Delta  value  X 

dy  Delta  value  Y 

ISizeLayer 


Change  layer  size 


Call:  result  =  SizeLayer(   1,   dx,   dy   ) 

dO  -66 (A6)  al  dO     dl 

LONG       result , dx, dy 
STRUCT  Layer  *1 

Function:     Changes  the  size  of  a  layer  relative  to  its  current  size. 
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Parameters:  1  Layer 

dx,dy  Relative  size  change 

Result:  0  Error 


SwapBitsRastPortClipKect 

Switch  contents  of  a  bit-map  and  ClipRect 


Call:  SwapBitsRastPortClipRect  (   rp,    cr   ) 

-126 (A6)  aO     al 

STRUCT  RastPort   *rp 
STRUCT  ClipRect   *cr 

Function:     Switches  the  contents  of  a  ClipRect  with  the  regions  of  a 
bit-map. 

Parameters:  rp  RastPort 

cr  ClipRect 

lUnlockLayer  Undo  a  LockLayerQ  caii] 

Call:  UnlockLayer(   1   ) 

-102 (A6)  aO 

STRUCT  Layer  *1 

Function:     Frees  the  layer  for  other  programs  to  use  again. 

Parameters:  1  Layer 

lUnlockLayerlnfo  Undo  LockLayerlnfoQ  caTT] 

Call:  UnlockLayerlnf o  (   li   ) 

-138 (A6)  aO 

STRUCT  Layer Info   *li 

Function:     Frees  the  Layerlnfo  structure  for  other  programs. 
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Parameters:  K  Layerlnfo 

|UnlockLayers  Undo  LockLayersQ  cali| 

Call:  UnlockLayers  (   li   ) 

-114 (A6)  aO 

STRUCT  Layerlnfo  *li 

Function:      Frees  the  entire  layer  system  in  the  given  Layerlnfo  list. 

Parameters:  b  Layerlnfo 


[UpfrontLayer  Move  a  layer  to  the  frontl 

Call:  result   =  UpfrontLayer  (   1    ) 

dO  -48 (A6)  al 

LONG       result 
STRUCT  Layer  *1 

Function:      Moves  a  layer  in  front  of  all  other  layers. 

Parameters:  1  Layer 

Result:  0  Error 

3.1.13        The  MathFFP,  MathlEEESingBas,  and 
MathlEEEDoubBas  Libraries 

The  Amiga  supports  three  different  floating  point  formats:  the 
international  IEEE  formats  for  32  and  64  bit  floating  point  numbers 
(which  can  be  directly  processed  by  the  FPU  68882),  and  the 
FastFloatingPoint  format. 

The  FFP  format  is  the  fastest  32  bit  floating  point  format  as  long  as  you 
don't  have  an  FPU,  which  will  process  the  IEEE  formats  faster  than  any 
CPU. 
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Two  libraries  exist  for  each  format.  First,  we  will  discuss  the  library  for 
basic  mathematical  functions.  The  functions  and  their  function  offsets  are 
the  same  for  all  three  libraries. 

MathFFP  functions  begin  with  'SF  and  expect  32  bit  FFP  values. 
MathlEEESingBas  functions  begin  with  'IEEESP'  and  expect  32  bit 
IEEE  values.  MathlEEEDoubBas  functions  begin  with  'IEEEEDF  and 
expect  64  bit  IEEEs. 

The  64  bit  numbers  are  always  distributed  across  two  registers  (upper  32 
bits/lower  32  bits). 

Functions  of  the  Base  Libraries 

Abs 

Add 

Ceil 

Cmp 

Div 

Fix 

Floor 

Fit 

Mul 

Neg 

Sub 

Tst 

Description  of  the  functions 
ISPAbs/IEEESPAbs/IEEEDPAbs  Absolute  value  \ 


Call: 

X                    = 

. . .Abs    ( 
-54 (A6) 

y  ) 

dO 

SPAbs 

dO 

dO 

IEEESPAbs 

dO 

dO/dl 

IEEEDPAbs 

dO/dl 

Function: 

Returns  the  positive  value  of  V. 
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ISPAdd/IEEESPAdd/IEEEDPAdd  Add  two  values] 

Call:  x  =         . .  .Add   (  y  ,        z   ) 

-66 (A6) 

dO  SPAdd  dO    dl 

dO      IEEESPAdd  dO    dl 

dO/dl   IEEEDPAdd  dO/dl  d2/d3 

Function:     x  =  y  +  z 

ISPCeil/IEEESPCeil/IEEEDPCeil  Round  up] 

Call:             x           =         .  .  .ceil  (  y  ) 

-96(A6) 

dO          SPCeil  dO 

dO      IEEESPCeil  dO 

dO/dl   lEEEDPCeil  dO/dl 

Function:      Rounds  'y'  to  the  next  whole  number  '>=y'. 

I  SPCmp/IEEESPCmp/IEEEDPCmp  Compare  values  1 

Call:  c  =         . .  .cmp    (  y  ,        z   ) 

-42 (A6) 

dO,cc  SPCmp  dl  dO 

dO,cc        IEEESPCmp  dl  dO 

dO.cc        IEEEDPCmp  dO/dl  d2/d3 

Function:     Compare  two  values. 

Result:  c=  l,cc  =  gt:y>z 

c  =  0,  cc  =  eq:  y  =  z 

c  =  -l,cc  =  lt:y<z 
|  SPDi  v/IEEESPDi  v/lEEEDPDi  v  Djvjsjon] 

Call: 


X 

... Div  (  y  , 

z 

-84 (A6) 

dO 

SPDiv   dO 

dl 

dO 

IEEESPDiv   dO 

dl 
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dO/dl        IEEEDPDiv       dO/dl  d2/d3 
Function:      x  =  y  /  z 
I  SPFix/IEEESPFix/IEEEDPFix  Convert  float  to  32  bit  integer  | 


Call: 

X        = 

.  ..Fix( 
-30 (A6) 

y  ) 

dO 

SPFix 

dO 

dO 

IEEESPFix 

dO 

dO 

IEEEDPFix 

dO/dl 

Function: 

Converts  floating  pc 

lint  num 

SPFloor/IEEESPFloor/IEEEDPFloor  Round  down| 


Call:  x  =  ...  Floor  (  y  ) 

-90 (A6) 
dO        SPFloor  dO 
dO    IEEESPFloor  dO 
dO/dl  IEEEDPFloor  dO/dl 

Function:     Rounds  'y'  to  the  next  whole  number  '<=y'. 

|  SPFIt/IEEESPFlt/IEEEDPFlt  Convert  long  to  floatl 

Call:  x  =  ...Flt(  y  ) 

-36 (A6) 

dO        SPFlt  dO 

dO    IEEESPFlt  dO 

dO/dl  IEEEDPFlt  dO 

Function:      Converts  a  32  bit  integer  to  a  floating  point  number. 

I SPMul/IEEESPMul  IEEEDPMul  Multiplication | 

Call:  x  =  . .  .Mul(  y  ,       z   ) 

-78 (A6) 

dO        SPMul  dO    dl 

dO    IEEESPMul  dO    dl 

dO/dl  IEEEDPMul  dO/dl  d2/d3 
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Function:     x  =  y  *  z 
I  SPNeg/IEEESPNeg/IEEEDPNeg 


Call:  x  =  . .  .Neg(  y  ) 

-60 (A6) 
dO       SPNeg  dO 
dO    IEEESPNeg  dO 
dO/dl  IEEEDPNeg  dO/dl 

Function:      x  =  -y 


|  SPSub/IEEESPSub/IEEEDPSub 


1  SPTst/IEEESPTst/IEEEDPTst 


Call:  c  =  ...  Tst  (  y   ) 

-48 (A6) 
dO,  cc     SPTst  dO 
dO, cc  IEEESPTst  dO 
dO,cc  IEEEDPTst  dO/dl 

Function:     Compares  a  value  with  0. 

Result:  c=  l,cc  =  gt:y>0.0 

c  =  0,  cc  =  eq:  y  =  0.0 
c  =  -l,cc  =  lt:y<0.0 


Negation] 


Subtraction] 


Call:  x  =  ...  Sub  (  y  ,       z   ) 

-72 (A6) 

dO        SPSub  dO    dl 

dO    IEEESPSub  dO    dl 

dO/dl  IEEEDPSub  dO/dl  d2/d3 

Function:     x  =  y  -  z 


Test  a  value] 
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3.1.14        The  MathTrans,  MathlEEESingTrans,  and 
MathlEEEDoubTrans  Libraries 

Now  we  will  look  at  the  libraries  for  trigonometrical  functions.  What  is 
true  for  the  basic  mathematical  functions  also  applies  to  these  functions. 

Trigonometrical  functions 

Acos 

Asin 

Atan 

Cos 

Cosh 

Exp 

Fieee 

Log 

LoglO 

Pow 

Sin 

Sincos 

Sinh 

Sqrt 

Tan 

Tanh 

Tieee 

Description  of  the  functions 

ISPAcos/IEEESPAcos/IEEEDPAcos  arc  cosliil 

Call:  x  =  ...  Acos  (  y   ) 

-120 (A6) 
d0  SPAcos     dO 

dO  IEEESPAcos     dO 

dO/dl   IEEEDPAcos     dO/dl 

Function:     Returns  the  arc  cos  of  'y'. 

[SPAsin/IEEESPAsin/IEEEDPAsin  arc  sln| 

Call:  x  =  . .  .Asin(  y  ) 

-114 (A6) 
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dO  SPAsin  dO 
dO  IEEESPAsin  dO 
dO/dl  IEEEDPAsin  dO/dl 

Function:      Returns  the  arc  sin  of  'y'. 


I  SPAtan/IEEESPAtan/IEEEDPAtan 


Call:  x  =  ...  Atan  (  y   ) 

-30 (A6) 
dO        SPAtan  dO 
dO    IEEESPAtan  dO 
dO/dl  IEEEDPAtan  dO/dl 

Function:      Returns  the  arc  tan  of  'y' • 


|  SPCos/IEEESPCos/IEEEDPCos 


Call:  x  =  ...  Cos  (  y   ) 

-42 (A6) 
dO        SPCos  dO 
dO    lEEESPCos  dO 
dO/dl  IEEEDPCos  dO/dl 

Function:      Returns  the  cos  of  'y'. 


|  SPCosh/IEEESPCosh/IEEEDPCosh 


Call:  x  =  ...  Cosh  (  y  ) 

-66 (A6) 
dO        SPCosh  dO 
dO    IEEESPCosh  dO 
dO/dl  IEEEDPCosh  dO/dl 


arc  tangent 


cosinl 


hyperbolic  cosin| 


Function:      Returns  the  hyperbolic  cos  of  'y'. 
ISPExp/IEEESPExp/IEEEDPExp  Exponential  function,  base  e| 


Call: 


X  = 

. . . Exp  (  y  ) 

-78 (A6) 

dO 

SPExp   dO 

dO 

IEEESPExp  dO 
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dO/dl  IEEEDPExp   dO/dl 

Function:     x  =  eAy 


|  SPFieee/IEEESPFieee/IEEEDPFieee 


Convert  IEEE  single  | 


Call: 


x  = 


Function: 


. . .Fieee(  y   ) 

-108 (A6) 
dO       SPFieee  dO 
(dO    IEEESPFieee  dO) 
dO/dl  lEEEDPFieee  dO 

Converts  a  32  bit  IEEE  value  to  the  format  of  the  current 
library. 


I  SPLog/IEEESPLog/IEEEDPLog 


Natural  logarithm] 


Call:  x  =  ...  Log  (  y   ) 

-84 (A6) 
dO        SPLog  dO 
dO    IEEESPLog  dO 

dO/dl  IEEEDPLog  dO/dl 

Function:      Returns  the  natural  log  of  'y'. 


ISPLoglO/IEEESPLoglO/IEEEDPLoglO  Logarithm,  base  10 1 


Call:  x  =  .  .  .Logl0(  y   ) 

-126 (A6) 
dO        SPLoglO  dO 
dO    IEEESPLoglO   dO 
dO/dl  IEEEDPLoglO  dO/dl 

Function:      Returns  the  base  10  log  of  'y'. 

ISPPow/IEEESPPow/IEEEDPPow 


Exponential  function] 


Call:  z  =  ...  Pow  (  x  ,       y  ) 

-90 (A6) 
dO        SPPow  dO    dl 
dO    lEEESPPow  dO    dl 
dO/dl  IEEEDPPow  dO/dl  d2/d3 
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Function:      z  =  xAy 

|  SPSin/IEEESPSin/IEEEDPSiiT 


sin 


Call:  x  =      . .  .sin(  y  ) 

-36 (A6) 

dO        SPSin  dO 

dO    IEEESPSin  dO 

dO/dl  IEEEDPSin  dO/dl 

Function:     Returns  the  sin  of  'y'. 


ISPSincos/IEEESPSincos/IEEEDPSincos 


Sin  and  Cosinl 


Call:  x  =  ...Sincos(  y,  z   ) 

-54 (A6) 

dO        SPSincos  dO    dl- 

dO    IEEESPSincos  dO    aO 

dO/dl  IEEEDPSincos  dO/dl  aO 

Function:      x  =  ...Sin(y)  AND  (z)=Cos(y).  'z'  is  the  address  of  the  cos 
result. 


|  SPSinh/IEEESPSinh/IEEEDPSinh 


Hyperbolic  sin) 


Call:  x  =  . .  .sinh(  y  ) 

-60 (A6) 
dO        SPSinh  dO 
dO    IEEESPSinh  dO 
dO/dl  IEEEDPSinh  dO/dl 

Function:     Returns  the  hyperbolic  sin  of  'y'. 

ISPSprt/IEEESPSqrt/IEEEDPSqrt 


Square  root] 


Call:  x  =  ...  Sqrt  (  y  ) 

-96 (A6) 
dO        SPSqrt  dO 
dO    IEEESPSqrt  dO 
dO/dl  IEEEDPSqrt  dO/dl 

Function:     Returns  the  square  root  of  'y'. 
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|  SPTan/IEEESPTan/lEEEDPTan 


Call:  x  =  ...  Tan  (  y  ) 

-48 (A6) 

dO  SPTan  dO 
dO  IEEESPTan  dO 
dO/dl  lEEEDPTan  dO/dl 

Function:      Returns  the  tangent  of  'y'. 


ISPTanh/IEEESPTanh/IEEEDPTanh 

Call:  x  =  ...  Tanh  (  y   ) 

-72 (A6) 

dO        SPTanh  dO 

dO    IEEESPTanh  dO 

dO/dl  lEEEDPTanh  dO/dl 


tangent  | 


Hyperbolic  tangent] 


Function:      Returns  the  hyperbolic  tangent  of  'y'. 

|  SPTieee/IEEESPTieee/IEEEDPTieee  Create  an  IEEE  single] 

Call:  x  =  ...Tieee(  y   ) 

-102 (A6) 
dO  SPTieee     dO 

(dO     IEEESPTieee     dO) 
dO     IEEEDPTieee     dO/dl 

Function:      Converts  a  value  from  the  library  format  to  a  32  bit  IEEE 
value. 


3.1 .1 5        The  Translator  Library 


The  "translatorJibrary"  consists  of  only  one  routine.  It  is  used  to  translate 
text  into  Phoneme  codes  for  the  Narrator  device. 

Description  of  function 


|  Translate" 


Generate  Phoneme  | 


Call:  rtnCode  =  Translate (inString,  inLength,  outBuffer,  outLength) 

DO        -30  (A6)    AO        DO        Al         Dl 
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LONG  rtnCode,inLength,outLength 
APTR  inString,outBuffer 

Function:     Translates  text  into  Phoneme  codes. 
Parameters:  inString      Text 

inLength    Text  length 

outBuffer    Buffer  for  Phonemes 

outLength  Buffer  length 

Result:  0  Okay,  otherwise  negative  cancel  offset  from 

start  of  text. 


3.1.16        The  Utility  Library 


The  "utility.library"  contains  helpful  routines  designed  to  make 
programming  easier.  One  of  the  most  important  things  you  can  do  with 
these  routines  is  construct  Tagltem  fields  from  high  level  languages. 

Functions  of  the  Utility  Library 

AllocateTagltems 

CloneTagltems 

FilterTagChanges 

FilterTagltems 

FindTagltem 

FreeTagltems 

GetTagData 

MapTags 

NextTagltem 

PackBoolTags 

RefreshTagltemClones 

TaglnArray 
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Description  of  the  functions 
|  AllocateTagltems  Allocate  a  Tagltem  field  | 

Call:  TagList  =  AllocateTagltems  (  Numltems  ) 

DO        -66 (A6)  DO 

STRUCT  Tagltem  *TagList 
ULONG  Numltems 

Function:     Allocates  a  Tagltem  field  for  storing  size,  etc.  Access  to  the 
tags  is  only  available  via  NextTagItem(). 

Parameters:  Numltems   Number  of  usable  slots. 

Result:  TagList  or  0 

|  CloneTagltems  Copy  a  Tagltem  field  | 

Call:  NewTagList  =  CloneTagltems  (  TagList   ) 

DO  -72 (A6)  AO 

STRUCT  Tagltem  *NewTagList, *TagList 

Function:     Copies  a  complete  Tagltem  list. 

Parameters:  TagList       Tagltem  list  to  be  copied. 

Result:  Tagltem  list  or  0 

|  FilterTagChanges  Filter  out  changes  to  a  Tagltem  field  | 

Call:  FilterTagChanges (  ChangeList,  OldValues,  Apply) 

-54  (A6)  AO  Al  DO 

STRUCT  Tagltem  *ChangeList, *01dValues 
LONG   Apply 

Function:     Replaces  all  unchanged  Tagltems  in  a  change  list  with 
TAG  IGNORE. 
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Parameters:  ChangeList 

New  Tagltems 

OldValues  Old  Tagltem  list 

Apply         Boolean,  indicates  whether  the  old  list  should 
be  used. 

I  FilterTagltems  Remove  certain  Tagltenis] 

Call:  nvalid     FilterTagltems (TagList,  TagArray,  Logic) 

DO    -96 (A6)       AO       Al        DO 

STRUCT  Tagltem  *TagList 
APTR   TagArray 
LONG   Logic 
ULONG  nvalid 

Function:     Replaces  with  TAGJGNORE  the  Tagltems  whose  ti_Tag 
entry  is  in  the  given  field. 

Parameters:  TagList       Tagltem  field 

TagArray    Field  with  the  tags  to  be  deleted,  ends  with 
TAG_END. 

Logic  TAGFILTER_AND  (delete  items  not  given  in 

the  field)  or  TAGFILTER_NOT  (delete  items 
given  in  the  field). 

Result:  Number  of  valid  items  remaining  in  the  list. 

I  FindTagltem  Find  a  Tagltiin] 

Call:  Tagltem  =  FindTagltem  (  TagVal,  TagList  ) 

DO        -30 (A6)       DO      AO 

STRUCT  Tagltem  *TagItem, *TagList 
LONG   TagVal 

Function:     Finds  an  item  in  a  Tagltem  list  with  the  given  tag  value. 
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Parameters:  TagVal        Tag  to  be  found 

TagList       Tagltem  list 
Result:  Tagltem  or  0 

|  FreeTagltems  Free  a  Tagltem  field  | 

Call:  FreeTagltems  (  TagList   ) 

-78 (A6)  AO 

STRUCT  Tagltem  *TagList 

Function:     Frees  a  Tagltem  field  allocated  with  AllocateTagItems()  or 
CloneTagItems(). 

Parameters:  TagList       Field  to  be  set  free. 

I  UetTagData  Get  data  on  a  Tagltem  | 

Call:  TagData  =  GetTagData(  TagVal,  Default,  TagList  ) 

DO         -3  6 (A6)      DO       Dl        AO 

ULONG  TagData , TagVal , Default 
STRUCT  Tagltem  *TagList 

Function:     Returns  the  ti_Data  entry  of  the  given  tag  or  the  default 
value  if  no  Tagltem  of  this  type  could  be  found. 

Parameters:  TagVal        Tag  to  be  found 

Default       Default  value 

TagList       List  to  be  searched 
Result:  ti_Data  or  'Default' 

IMapTags  Change  tags] 

Call:  MapTags (TagList,   MapList,    IncludeMiss) 

-60 (A6)    AO  Al  DO 
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STRUCT  Tagltem  *TagList, *MapList 
BOOL   IncludeMiss 

Function:      Tags  that  are  to  be  replaced  by  the  ti_Tag  of  the  given  list 
are  given  in  a  'MapList'  as  ti_Data  entries. 

Parameters:  TagList       List  with  tags  to  be  changed. 

MapList     List  with  changes 

IncludeMiss 

Boolean,  whether  items  not  in  the  MapList 
should  remain  unchanged  (otherwise  they  are 
replaced  with  TAGJGNORE). 

I  NextTagltem  Find  the  next  normal  Tagltem  | 

Call:  Tagltem  =  NextTagltem  (  TagltemPtr  ) 

DO        -48 (A6)       AO 

STRUCT  Tagltem  *TagItem, **TagItemPtr 

Function:     Returns  the  next  Tagltem,  skipping  over  all  system  tags. 

Parameters:  TagltemPtr  Address  of  a  longword  with  the  address  of  the 

first  Tagltem. 

Result:         Tagltem  or  0 

|  PackBoolTags  Combine  BoolTags  into  a  Hag  longword | 

Call:  Flags  =  PackBoolTags  (  InitialFlags,  TagList,  BoolMap  ) 

DO      -42 (A6)       DO  AO       Al 

ULONG  Flags, InitialFlags 

STRUCT  Tagltem  "TagList, *BoolMap 

Function:     BoolTags  are  entered  as  bit  flags  in  a  longword.  The  tag 
flags  are  given  as  tiJData  in  a  Tagltem  field. 

Parameters:  InitialFlags  Default  result 
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TagList       Tagltem  field  with  BoolTags 

BoolMap    Tagltem  field  with  flag  longwords 

Result:  Changed  flag  longword 

Example:  Assume  that  we  are  managing  the  IDCMP  Flags  in  a 
complex  program  using  Tagltems,  and  now  we  want  to 
assemble  the  IDCMPFlag  longword: 


**  Definition  of  the 

** 

Tags 

TAG_NEWSIZE 

= 

TAG_USER+1 

TAG_REFRESHWINDOW 

= 

TAG_USER+2 

TAG_MOUSEBUTTONS 

= 

TAG_USER+3 

TAGJKOUSEMOVE 

= 

TAG_USER+4 

TAG_GADGETDOWN 

= 

TAG_USER+5 

TAG_GADGETUP 

= 

TAG_USER+6 

TAG_REQSET 

= 

TAG_USER+7 

TAG_MENUPICK 

= 

TAG_USER+8 

TAG_CLOSEWINDOW 

= 

TAG_USER+9 

TAG_RAWKEY 

= 

TAG_USER+10 

TAG_REQCLEAR 

= 

TAG_USER+11 

TAG_NEWPREFS 

= 

TAG_USER+12 

TAG_DISKINSERTED 

= 

TAG_USER+13 

TAG_DISKREMOVED 

= 

TAG_USER+14 

TAG_ACTIVEWINDOW 

= 

TAG_USER+15 

TAG_INACTIVEWINDOW 

= 

TAG_USER+16 

TAG_DELTAMOVE 

= 

TAG_USER+17 

TAG_VANILLAKEY 

= 

TAG_USER+18 

TAG_INTUITICKS 

= 

TAG_USER+19 

TAG_MENUHELP 

= 

TAG_USER+20 

TAG_CHANGEWINDOW 

= 

TAG_USER+21 

** 

**  Example 

** 

movea.l  _MainWindow,al 
lea     ..Changes (pc) , aO 
bsr     _Set IDCMP 

..Changes 

dc . 1    TAG_MOUSEMOVE , 0 
dc . 1     TAG_GADGETDOWN , 0 


;turn  off 
;turn  off 
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dc. 

,1 

TAG_DELTAMOVE, 0 

;turn  off 

dc. 

,1 

TAG_VANILLAKEY, -1 

;turn  on 

dc. 

.1 

TAG_USER+40,-l 

;no  meaning 

dc. 

,1 

TAG_RAWKEY,0 

;turn  off 

dc. 

.1 

TAG_MOUSEBUTTONS, -1 

;turn  on 

dc 

.1 

TAG_USER+35,0 

;no  meaning 

dc 

.1 

TAG_DONE 

**  Change  IDCMPFlags 

** 

**  Input:  al=Window,  aO=TagItems 

** 

_SetIDCMP 
movem.l  al/a6,-(a7) 
movea.l  _UtilityBase,a6 
move . 1      wd_IDCMPFlags (al ) , dO 
lea  _BoolMap(pc) ,al 

j  sr  _LVOPackBoolTags ( a6 ) 

movea.l    (a7)+,a0 
movea.l  _IntuiBase,a6 
jsr  _LVOModifyIDCMP(a6) 

movea.l    (a7)+,a6 
rts 

_BoolMap 
del    TAG_NEWSIZE,2 
dc . 1   TAG_REFRESHWINDOW , 4 
dc . 1   TAG_MOUSEBUTTONS , 8 
dc . 1   TAG_MOUSEMOVE ,$10 
del   TAG_GADGETDOWN ,$20 
del   TAG_GADGETUP,  $40 
del   TAG_REQSET,  $80 
del  TAG_MENUPICK,  $100 
dc . 1   TAG_CLOSEWINDOW, $200 
del  TAG_RAWKEY,$400 
del   TAG_REQCLEAR, $1000 
dc . 1  TAG_NEWPREFS ,$4000 
del   TAG_DISKINSERTED,$8000 
dc . 1   TAG_DISKREMOVED, $10000 
dc . 1   TAG_ACTIVEWINDOW, $40000 
dc . 1    TAG_INACTIVEWINDOW ,$80000 
del   TAG_DELTAMOVE ,$100000 
dc . 1   TAG_VANILLAKEY ,$200000 
del   TAG_INTUITICKS,  $400000 
dc . 1   TAG_MENUHELP, $1000000 
del   TAG_CHANGEWINDOW,  $2000000 
del   TAG_D0NE 
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I  RefreshTagltemClones  Reset  a  copied  Tagltem  field  I 

Call:  Ref reshTagltemClones (  CloneTagltems,  OriginalTagltems  ) 

-84 (A6)  AO  Al 

STRUCT  Tagltem  "CloneTagltems, *OriginalTagItems 

Function:     Restores  a  list  obtained  with  CloneTagItems()  to  the  values 
of  the  original  list. 

Parameters:  CloneTagltems 

Result  from  CloneTagltems  (original  Tagltems). 

OriginalTagltems 

Unchanged  original  list 

I  Tagln  Array  check  if  a  tag  is  present! 

Call:  Bool  =  TagInArray(   Tag,    TagArray   ) 

DO  -90 (A6)  DO        AO 

ULONG  Tag 
APTR     TagArray 

Function:     Checks  for  a  certain  value  in  a  tag  value  field  ending  with 
TAG_END. 

Parameters:  Tag  Tag  value  to  search  for. 

TagArray    Field  with  tag  values,  ends  with  TAG_END. 

Result:  0  Value  not  found. 


Dec  Hex  STRUCTURE  Tagltem, 0 

0  $0  ULONG    ti_Tag       ;ID  (TAG_...) 

4  $4  ULONG   ti_Data      ; ID-specific  data 

8  $8  LABEL    ti_SIZEOF 

TAG_DONE   =         0  ;end  of  a  Tagltem  field 
TAG_IGNORE  =         1  ;skip  Tagltem 
TAG_MORE    =         2  ;next  Tagltem  field 

TAG_USER   =  $80000000 
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3.1.17        The  Workbench  Library 


The  Workbench  used  to  be  a  task  module.  Starting  with  AmigaOS  2.0,  it 
is  now  a  library.  The  functions  of  the  "workbench.library"  allow  you  to 
create  menus  and  icons  in  the  Workbench  window. 

Functions  of  the  Workbench  Library 

AddAppIconA 

AddAppMenuItemA 

AddAppWindowA 

RemoveAppIcon 

RemoveAppMenuItem 

RemoveApp  Window 

Description  of  the  functions 


|  AddAppIconA 


Add  custom  icons  to  the  Workbench  | 


Call: 


Applcon  =  AddAppIconA(id,  userdata,  text,  msgport,  look,  diskobj,  tag list) 
DO        -60 (A6)      DO  Dl        AO    Al       A2    A3       A4 


STRUCT  Applcon  *AppIcon 
ULQNG  Id,  userdata 

APTR        text 

STRUCT  MsgPort  *msgport 

BPTR       lock 

STRUCT  Diskobject  *diskobj 

STRUCT  Tagltem  *taglist 


Function:  Creates  a  custom  icon  and  adds  it  to  the  Workbench.  Two 
types  of  events  are  generated  by  the  icon:  a  double-click 
on  the  icon  (am_NumArgs=0)  and  dragging  another  icon 
across  it  (like  WbStartup  message). 


Parameters:  id 


Custom  ID  value 


userdata     Custom  data 


text 
lock 


Icon  name 
File  lock  or  0 
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msgport      MsgPort     for     AppMessages     of     type 
MTYPE_APPICON. 

diskobj       Address  of  a  DiskObject  structure. 

taglist         Tagltem  field  or  0 
Result:  Applcon  structure  or  0 

|AddAppMenuItemA 


Add  a  Menultem  to  the  Tools  menu] 


C0//.'  AppMenuItem  =  AddAppMenuItemA(id,   userdata,   text,  msgport,   taglist) 

DO  -72 (A6)  DO     Dl  AO         Al  A2 

STRUCT  AppMenuItem  ^AppMenuItem 

ULONG     id,  userdata 

APTR       text 

STRUCT  MsgPort  *msgport 

STRUCT  Tagltem  *taglist 

Function:      Adds  a  menu  item  to  the  Tools  menu  of  the  Workbench. 
Parameters:  id  Custom  ID  value 

userdata     Custom  data 

text  Item  text 

msgport      MsgPort     for     AppMessages     of     type 
MTYPE_APPMENUITEM. 

taglist         Tagltem  field  or  0 

Result:  AppMenuItem  structure  or  0 

Example:      Add  a  menu  item  to  the  Workbench  Tools  menu: 


movea.l  $4.w,a6  ;ExecBase 

jsr     _LVOCreateMsgPort(a6)  ;get  MsgPort 

move.l  dO,_MsgPort  ;and  save 
beq     _Zerror 
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movea . 1 

_WbenchBase , a6 

; "workbench. library 

moveq 

#l,dO 

;ID 

moveq 

#0,dl 

;User  data 

lea 

_ItemText (pc) , aO 

;menu  item 

movea . 1 

_MsgPort,al 

;MsgPort 

suba.l 

a2,a2 

;no  Tags 

jsr 

_LVOAddAppMenuItemA ( a6 ) 

;add 

move . 1 

dO , _AppMenuItem 

; save  result : 

beq 

_Zerror2 

movea . 1 

$4.w,a6 

; ExecBase 

movea . 1 

_MsgPort ,  aO 

;  Port 

jsr 

_LV0GetMsg(a6) 

;get  message 

tst.l 

dO 

;and  test 

beq 

_NoMessage 

movea . 1 

dO.al 

cmpi .w 

#MTYPE_APPMENUITEM, 

, am_Type (al) 

;menu  selected? 

bne 

_NextMessage 

moveq 

#l,dO 

cmp.l 

am_ID(al) ,d0 

;our  ID? 

bne 

_NextMenu 

jsr 

_LVOReplyMsg(a6) 

_MenuChoice 

movea . 1  _WbenchBase , a6 

movea . 1  _AppMenuItem, aO 

jsr     _LVORemoveAppMenu I t em ( a 6 ) 

movea. 1  $4.w,a6 
_Loop 

movea . 1  _MsgPort , aO 

jsr     _LVOGetMsg ( a6 ) 

tst.l   dO 

beq.s   _DelPort 

movea. 1  dO.al 

jsr     _LVOReplyMsg(a6) 

bra . s   _Loop 
_DelPort 

movea . 1  _MsgPort , aO 

jsr     _LVODeleteMsgPort(a6) 


.ItemText 
dc.b    'My  Menu',0 
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_MsgPort 
ds.l    1 

_AppMenuItem 
ds.l    1 


|  Add  App  Window  A  Add  a  window  to  the  Workbench 


Cfl//.°  AppWindow  =  AddAppWindowAUd,  userdata,  window,   msgport,    taglist) 

DO  -48  (A6)  DO     Dl  AO  Al  A2 

STRUCT  AppWindow  "AppWindow 
ULONG     id.userdata 
STRUCT  Window  'window 
STRUCT  MsgPort  *msgport 
STRUCT  Tagltetn  *taglist 

Function:     Adds   a  window  to   the  Workbench  list  and   sends 
notification  of  all  objects  placed  in  the  window. 

Parameters:  id  Custom  ID  value 

userdata     Custom  data 

window      Window 

msgport      MsgPort     for     AppMessages     of     type 
MTYPE_APPWINDOW. 

taglist         Tagltem  field  or  0 

Result:  AppWindow  structure  or  0 

|  Remove Applcon  Remove  icon  from  the  Workbench  | 

Call:  error  =  RemoveApplcon  (Applcon) 

DO  -66 (A6)  AO 

BOOL       error 

STRUCT  Applcon  *AppIcon 
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Function:     Undo  AddAppIconA(). 

Parameters:  Applcon     Result  from  AddAppIconA(). 

Result:  0  Error 

|  RemoveAppMenuItem  Remove  item  from  the  Tools  menu  | 

Call:  error  =  RemoveAppMenuItem  (AppMenuItem) 

DO  -78  (A6)  AO 

BOOL        error 

STRUCT  AppMenuItem  *AppMenultem 

Function:      Undo  AddAppMenuItemA(). 

Parameters:  AppMenuItem 

Result  from  AddAppMenuItemA(). 

Result:  0  Error 

|  Remove App Window  Remove  window  from  Workbench  | 

Call:  error  =  RemoveAppWindow(AppWindow) 

DO  -54  (A6)  AO 

BOOL       error 

STRUCT  AppWindow  *AppWindow 

Function:      Undo  AddAppWindowA(). 

Parameters:  AppWindow 

Result  from  AddAppWindowA(). 

Result:  0  Error 

WBDISK    =  1  ;object  types:  diskette 

WBDRAWER  =  2  ;  directory 

WBTOOL    =  3  ;  program 

WBPROJECT  =  4  ;  file 

WBGARBAGE  =  5  ;  trash  can 

WBDEVICE  =  6  ;  device  driver 

WBKICK    =  7  ;  OS  disk 
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WBAPPICON 


user  icon 


Dec  Hex  STRUCTURE  DrawerData,0 


0   $0  STRUCT 
48  $30  LONG 
52  $34  LONG 
56  $38  LABEL 
56  $38  ULONG 
60  $3C  UWORD 
62  $3E  LABEL 


dd_NewWindow,nw_SIZE  ;for  OpenWindowO 
dd_CurrentX         /position 
dd_CurrentY  / 

01dDrawerData_SIZEOF  /previous  structure  size 

; Flags 

;view  mode 

;size  of  structure  starting  with  v3  6 


dd_Flags 

dd_ViewModes 

DrawerData_SIZEOF 


DRAWERDATAFILESIZE  =  DrawerData_SIZEOF 


Dec 

Hex  STRUCT! 

0 

$0  UWORD 

2 

$2  UWORD 

4 

$4  STRUCT 

48 

$30  UBYTE 

49 

$31  UBYTE 

50 

$32  APTR 

54 

$36  APTR 

58 

$3A  LONG 

62 

$3E  LONG 

66 

$42  APTR 

70 

$46  APTR 

74 

$4A  LONG 

78 

$4E  LABEL 

do_Magic  ; start  ID:  $e310 

do_Version  /version  number  of  the 

do_Gadget,gg_SIZEOF  /Gadget  structure 

do_Type 

do_PAD_Byte 

do_DefaultTool 

do_ToolTypes 

do_CurrentX 

do_CurrentY 

do_DrawerData 

do_ToolWindow 

do_StackSize 

do_SIZEOF 


structure 


/only  with  Tools 
/only  with  Tools 


WB_DISKMAGIC  =  $e310 
WB_DISKVERSION  =  1 
WB_DISKREVISION  =  1 
WB_DISKREVISIONMASK  =  $ff 
GADGBACKFILL  =  1 
NO_ICON_POSITION     =  $80000000 


ID 

version 

revision:  lower  8  bits  gg_Userdata 


Dec  Hex  STRUCTURE  FreeList.O 
0   $0  WORD    fl_NumFree 
2   $2  STRUCT  fl_MemList,LH_SIZE 
16  $10  LABEL   FreeList_SIZEOF 


MTYPE_PSTD  =  1 

MTYPE_TOOLEXIT  =  2 

MTYPE_DISKCHANGE  =  3 

MTYPE_TIMER  =  4 

MTYPE_CLOSEDOWN  =  5 

MTYPE_IOPROC  =  6 

MTYPE_APPWINDOW  =  7 


/standard  message 

/ExitMessage  from  Tools 

/disk  change 

/timer  tick 

/ not  imp 1 ement ed 

;not  implemented 

/Msg  for  application  window 
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MTYPE_APPICON 
MTYPE_APPMENUITEM 
MTYPE_COPYEXIT 
MTYPE_ICONPUT 


=  8  ;Msg  for  application  icon 

=  9  ;Msg  for  application  menu 

=10  ;end  of  a  copy  process 

=11  ;Msg  from  icon.library/PutDiskObject ( ) 


AM_VERSION   =  ' 

.  .-version  of  folloi 

Dec 

Hex 

STRUCTURE  AppMessage,0 

0 

$0 

STRUCT 

am_Message , MN_SIZE 

20 

$14 

UWORD 

am_Type 

22 

$16 

ULONG 

am_UserData 

26 

$1A 

ULONG 

am_ID 

30 

$1E 

LONG 

am_NumArgs 

34 

$22 

APTR 

am_ArgList 

38 

$26 

UWORD 

am_Version 

40 

$28 

UWORD 

am_Class 

42 

$2A 

WORD 

am_MouseX 

44 

$2C 

WORD 

am_MouseY 

46 

$2E 

ULONG 

am_Seconds 

50 

$32 

ULONG 

am_Micros 

54 

$36 

STRUCT 

am_Reserved, 8 

62 

$3E 

LABEL 

AppMes  sage_S I ZEOF 

StandardMessage 
message  type 
user  data 

number  of  arguments 
arguments 
AM_VERSION 
message  class 
mouse  position 

even  time 


STRUCTURE  AppWindQW, 0    ; PRIVATE 


STRUCTURE  AppIcon.O 


; PRIVATE ! 


STRUCTURE  AppMenuItem, 0  /PRIVATE! 


Dec  Hex  STRUCTURE  WBStartup.O 

0   $0  STRUCT  sm_Message,MN_SIZE 
20  $14  APTR    sm_Process 


24  $18  BPTR 
28  $1C  LONG 
32  $20  APTR 
36  $24  APTR 


sm_Segment 
sm_NumArgs 

sm_ToolWindow 
sm_ArgList 


; Process 

;SegList 

; number  of  arguments 

; window 

; argument  field 


40  $28  LABEL    sm_SIZEOF 


Dec  Hex  STRUCTURE  WBArg.O 

0   $0  BPTR    wa_Lock  ; directory  lock 
4   $4  APTR    wa_Name  ;file  name 
8   $8  LABEL   wa_SIZEOF 
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Part  2  -  Introduction 


Part  2  -  Introduction 


ARexx  -  by  now  it's  a  buzzword  in  the  Amiga  community.  ARexx  is  a 
logical  evolution  of  CLI  and  CLI  commands.  As  a  command  language,  it 
controls  external  applications.  You  can  use  ARexx  to  tell  a  word 
processor  to  format  text  and  then  tell  the  desktop  publishing  program 
(using  ARexx)  to  import  and  print  the  text.  ARexx  was  conceived  as  a 
commercial  product.  Starting  with  the  AmigaOS  2.0,  it  is  a  component  of 
the  Amiga  operating  system.  Compared  to  simple  CLI  commands, 
variable  manipulation  is  easier,  and  because  variable  manipulation  is 
simple,  ARexx  is  at  least  as  powerful  as  BASIC.  But  can  BASIC 
indirectly  control  application  programs? 

Author:  Christian  Kuhnert 
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4.     ARexx 


ARexx  is  not  new.  Since  1987,  the  Amiga  version  of  Rexx  by  William  S. 
Hawes  has  been  commercially  available.  Since  then,  ARexx  has  become 
the  de-facto  standard  for  external  program  control  on  the  Amiga.  No 
serious  commercial  program  can  afford  not  to  access  the  ARexx-Port  as 
part  of  the  Amiga  multitasking  operating  system. 

Including  ARexx  in  the  Amiga  2.0,  as  a  component  of  the  operating 
system,  was  the  next  logical  step  for  Commodore.  This  decision  can  also 
be  interpreted  as  a  decision  against  other  models  of  processor 
communication,  like  the  IPC  project  in  the  PD  field,  an  approach  that  is 
not  as  complex,  but  also  not  as  flexible. 

This  book  is  not  intended  to  be  a  complete  guide  to  programming  in 
ARexx;  our  focus  is  how  an  interrupt  directed  to  ARexx  can  make 
application  programs  configurable,  expandable  and  sometimes  enable 
connection  to  other  programs. 

An  experienced  user  of  structured  programming  languages  like  C, 
Modula,  or  Pascal  (or  any  BASIC  dialect  with  structured  form)  will 
understand  ARexx  immediately. 


4.1      The  ARexx  Language 


Rexx  is  the  name  of  a  programming  language  that  was  developed  at  two 
IBM  research  sites  in  England  and  the  USA  between  1979  and  1982.  Its 
main  characteristics  are: 

•  Universal  applicability:  Rexx  is  not  dedicated  to  a  certain 
application  (or  application  type).  Many  programming  languages 
make  this  claim  and  ARexx  is  actually  better  suited  to  applications 
that  value  higher  running  speed  over  programming  speed. 

"Type-less"  data:  all  data  are  treated  as  character  strings  at  first.  No 
type  classification  takes  place  until  a  specific  operation  is 
performed.  Defined  data  types  such  as  integers,  floating  decimals, 
bytes  and  words  are  not  natural  limits,  but  machine  terms.  These  are 
limitations  Rexx  developers  intended  to  avoid. 
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No  declarations:  variables  must  not,  as  in  many  programming 
languages,  be  declared  before  use;  in  this  sense,  Rexx  is  like  BASIC 
or  APL.  Even  very  large  data  fields  do  not  have  to  be  previously 
dimensioned. 

Only  a  few  basic  commands:  about  10  commands  are  sufficiently 
powerful  to  create  complex  programs.  There  are  a  total  of  about  30 
commands. 

Easy  string  manipulation:  the  scope  of  the  language  includes  many 
functions  that  perform  string  manipulation,  which  makes  this  aspect 
more  developed  than  in  other  languages. 

Easy  error  trapping:  the  Rexx  interpreter  has  a  powerful  TRACE 
function.  The  trace  function  also  enables  interruptions  during 
program  execution. 

"Human"  Logic:  instead  of  following  firm  syntax  formalities,  Rexx 
normally  does  what  is  intuitively  right.  This  means  that  if  you  just 
think  about  the  problem,  you  will  usually  come  to  the  correct  result 
without  looking  anything  up. 
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4.2     The  Functions  of  ARexx 

Because  it  transmits  input  to  the  processor,  Rexx  is  especially  well-suited 
as  a  script  or  batch  language  for  automatic  control  of  an  operating 
system  or  as  a  macro  language.  These  operations  are  the  same  thing,  but 
in  the  latter  case,  Rexx  controls  an  application  program. 

Almost  every  operating  system  has  a  shell  or  batch  language;  each  has  its 
specific  features  and  special  functions.  The  same  holds  true  for  macro 
languages  that  are  specially  designed  to  configure  and  control  an 
individual  program,  such  as  an  editor  or  a  database  manager. 

Rexx  was  developed  with  an  eye  toward  becoming  a  universal  command 
language.  Rexx  can  pass  commands  to  an  external  environment  (or  an 
operating  system)  and  receive  an  answer  in  return. 

Rexx  is  also  capable  of  acting  as  a  universal  programming  language, 
because  it  enables  the  creation  of  function  libraries.  These  effectively 
expand  the  scope  of  the  language  itself.  Specifically,  Rexx  makes 
program  development  and  testing  quick  and  easy. 
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4.3     An  Overview  of  ARexx 

All  Rexx  programs  begin  with  a  C-style  comment.  "/*"  is  expected  at  the 
beginning  of  the  program  by  the  interpreter.  This  convention  encourages 
the  programmer  to  document  the  purpose  of  the  program  with  a  short 
comment.  A  complete  Rexx  program  would  appear  as  follows: 

/*  A  simple  example  program  */ 
SAY  "I  am." 

SAY  is  a  Rexx  command.  It  displays  the  following  expression,  which  is  a 
character  string.  You  do  not  have  to  type  commands  in  capital  letters;  the 
interpreter  only  differentiates  between  large  and  small  letters  within 
character  strings.  Double  quotation  marks  (")  or  simple  quotations  (') 
define  a  character  string. 

The  simplest  counterpart  to  "say"  is  "pull": 

/*  Calculate  body  weight  in  engl.  stones  */ 
say  "Please  enter  your  body  weight  in  Kg!" 
pull  weight 
say  "That  equals"  weight/ 6. 3 48  "stones." 

PULL  waits  for  a  user  entry  and  assigns  it  to  the  variable  ("weight").  As 
you  can  see,  the  variable  name  did  not  need  to  be  specified.  Even  an 
error  in  user  entry  (like  typing  a  letter)  would  have  no  consequences  in 
the  "Pull"  line,  since  variables  always  contain  character  strings.  Once  the 
string  is  divided  in  the  last  line,  the  input  must  be  interpreted  as  a  number 
with  a  floating  decimal.  An  error  message  does  not  appear  until  the 
division  in  the  last  line  is  impossible;  then  the  program  stops.  Numbers 
can  be  written  with  a  decimal  point  or  in  exponential  notation.  By  using 
the  NUMERIC  setting,  the  number  of  decimal  places  can  be  set. 

Although  it  doesn't  appear  to  mean  anything,  the  space  character 
between  the  two  expressions  is  also  an  operator  for  the  SAY  command. 
The  space  indicates  that  it  should  concatenate  with  a  space  inserted  in 
the  program. 

The  empty  space  can  also  be  inserted  within  the  two  strings.  Then  the 
individual  expressions  are  directly  concatenated;  this  too  forces 
concatenation,  but  without  additional  empty  spaces. 
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An  explicit  concatenation  operator  also  exists:  "II"  -  it  directly  connects 
the  contents  of  two  variables,  without  an  empty  space. 

Rexx  has  all  the  usual  commands  for  program  control.  The  most 
important  and  complex  of  these  is  the  DO  ...END  group,  which  (like 
BEGIN...END  in  Pascal,  or  {...}  in  C)  is  a  simple  command  grouping.  It's 
used  to  control  the  formation  of  program  loops:  a  sub-keyword 
FOREVER  sets  up  unlimited  repetition,  a  run-time  variable  can  increment 
to  a  maximum  value,  or  a  BY  can  issue  a  step  width.  A  FOR  sets  a 
maximum  number  of  loops.  Program  termination  conditions  are  WHILE 
or  UNTIL.  These  commands  can  be  combined  in  a  meaningful  manner 
with  other  commands  that  iterate  and  leave,  go  to  the  next  step,  or  exit 
from  loops. 

There  is  also  an  IF...THEN...ELSE  construction  and  a  process  like 
"switch"  in  C,  called  SELECT...WHEN...OTHERWISE...END.  There  is  no 
"Goto"  command.  The  SIGNAL  command  jumps  to  labels  within  a 
calculation,  but  not  within  command  groups  or  loops.  These  always 
terminate  with  the  SIGNAL  command.  Together,  all  of  these  lead  to 
clearly  structured  programming. 

/*  Calculate  factor  */ 

ARG  number  /*  read  in  argument  */ 

result=l  /*  result (-ing)  variable  initialized  */ 

if  number<0  /*  For  negative  entry  */ 

then  return        /*  cancel  */ 
do  n=l  to  number      /*  Loop  with  run-time  variable  n  */ 

result=result*n 

end  n  /*  the  entry  'n'  is  optional  */ 

say  number"!  ="  result 

Along  with  the  use  of  a  "do"  loop,  this  example  shows  another  possible 
method  of  data  entry:  ARG  reads  arguments  listed  after  the  Rexx 
command  into  variables. 

If  this  program  is  started  by  entering  RX  FACULTY  7,  the  "number" 
receives  the  value  "7".  If  the  "if  query  receives  a  negative  number,  it 
cancels  the  program  with  the  RETURN  command. 

If  the  input  is  over  171,  the  result  is  not  correct.  1. 797693 14E+308  is  the 
upper  limit  for  the  program.  An  error  message  "Arithmetic  overflow"  is 
not  implemented  in  ARexx  1.14. 
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ARexx  requires  a  certain  amount  of  care  when  dealing  with  very  large  or 
very  small  numbers,  since  false  results  do  occur.  The  reason  for  such 
limitations  may  be  ARexx's  use  of  the  mathieeedoubbas.library  for  all 
arithmetic  calculations.  Perhaps  this  will  be  changed  in  future  versions. 

In  the  next  example,  the  program  is  defined  as  an  internal  function.  For 
Rexx,  functions  are  a  part  of  the  language,  defined  in  programs  or 
externally  accessed  in  libraries. 

/*  example  for  function  definition  and  call  */ 
do  n=l  to  9 

say  n"!  ="  fak(n)     /*  call  fak  */ 
end  n 

return        /*  program  end  */ 
fak:  procedure       /*  function  name;  local  variable  */ 
ARG  number  /*  read  argument  */ 

result=l 
if  number<0 

then  return  " Error ! " 
do  n=l  to  number 

result =result*n 
end  n 
return  result         /*  end  the  function  with  value  output*/ 

The  function  "fak"  is  defined  in  the  lines  after  the  label  "fak:".  The  key 
word  PROCEDURE  is  necessary  because  the  main  program  uses  the 
same  run-time  variable  ('n')  as  this  function.  A  separate  variable 
environment  is  defined  for  the  function,  so  the  program  works  with  local 
variables. 

ARG  reads  arguments  (given  in  the  parentheses)  at  the  function  call  and 
ends  the  function  with  a  return.  It  outputs  the  background  expression 
and  replaces  the  call  with  that  value. 
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4.4     ARexx  -  Rexx  on  the  Amiga 

ARexx  is  a  version  of  Rexx  that's  used  on  the  Amiga  as  a  command  and 
macro  language.  Rexx's  rather  unusual  mathematic  capabilities  are 
considered  less  important  than  its  program  control  features.  ARexx  is 
easy  to  use  and  many  operating  tasks  can  be  automatically  handled  by 
the  interpreter.  Compared  to  the  standard  version,  this  version  is  slightly 
expanded.  Unfortunately,  because  of  changes  in  file  operations,  porting 
data  is  more  difficult 

However,  the  expansions  are  used  to  adapt  the  Rexx  language  to  the 
qualities  of  the  Amiga.  Although  this  makes  the  language  easier  to  use,  it 
also  decreases  its  speed.  Amiga  BASIC  is  about  six  times  faster  than 
ARexx  (Version  1.12).  Although  the  running  speed  can  be  increased 
slightly,  ARexx  isn't  suitable  for  large-scale  programming. 

Because  all  data  are  handled  as  strings,  which  require  frequent  internal 
conversions,  and  functions  are  called  by  runtime  linking,  this  language 
offers  limited  programming  possibilities.  In  the  future,  a  compiler  for 
ARexx  may  be  available.  If  this  happens,  further  applications  may  be 
possible.  However,  even  compiled  code  would  barely  reach  the  speeds  of 
C-compiled  applications. 

The  core  of  the  ARexx  system  is  the  Rexx  master  procedure,  which 
manages  function  libraries  and  common  data  structures.  This  procedure 
waits  in  the  background  for  the  start  of  an  ARexx  program,  which  is 
often  performed  using  the  CLI  program  "rx".  Any  program  can  use  the 
Rexx  port  to  call  a  Rexx  program.  Rexx  searches  the  current  directory 
and  then  a  logical  device  named  Rexx:  (if  it  is  installed)  for  the  desired 
program. 

Every  ARexx  program  starts  a  separate  task  that  reads  and  executes  the 
source  code  with  the  Rexxsyslib.library,  which  contains  the  actual 
interpreter.  In  this  way,  an  unlimited  number  of  ARexx  programs  can  be 
run  simultaneously,  even  with  limited  storage  capacity. 
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4.5     A  Sample  Application 


The  following  program  can  be  used  to  experiment  with  the  Rexx 
language.  A  simple  line  interpreter  can  be  used  to  execute  ARexx 
commands  directly  and  interactively.  It  can  also  be  expanded  to  become 
a  complete  and  easy-to-use  shell,  fully  replacing  the  CLI. 

A  Rexx  program  can  be  created  using  any  editor.  If  you  want  to  run  it 
from  CLI,  give  it  the  tag  .Rexx  and  store  it  in  the  "Rexx:"  directory.  Call 
it  from  CLI  by  typing  "rx  program_name".  If  the  Rexx  master  procedure 
is  not  already  running,  "rx"  starts  it  and  then  executes  the  Rexx  program. 

/*  interactive  Rexx  interface  */ 

address  command  /*  command  destination  is  the  CLI  */ 

options  prompt  "Rexx>  "        /*  A  prompt  for  pull  */ 

start:  /*  entry  point  at  error  */ 

signal  on  syntax  /*  At  error  moves  to  the  equivalent  */ 

signal  on  error  /*  label  branching  instead  cancel  */ 

do  forever  /*  endless  loop  */ 

parse  pull  input  /*  Wait  for  entry  */ 

interpret  input  /*  execute  entry  as  an  ARexx  line  */ 

end  /*  next  loop  */ 

syntax:  /*  at  syntax  error  output  message  */ 

say  "Error"  re  "in  line"  sigl":"  errortext (re) 
signal  start  /*  . . .and  so  forth*/ 

error:  /*  at  command  error  ...*/ 

say  "Returncode: "  re         /*  ...output  Returncode  */ 
signal  start  /*  ...and  so  forth*/ 

The  ADDRESS  sets  the  destination  for  the  external  command.  Rexx 
views  all  free-standing  expressions  (those  that  are  not  used  by  a  Rexx 
command)  as  expressions  that  are  to  be  transmitted  to  an  external 
environment. 

To  specify  DOS  as  the  recipient,  use  the  COMMAND  address;  otherwise 
the  name  of  the  Rexx  Message  Port  would  be  the  called  program. 

The  OPTIONS  prompt  is  a  specific  command  for  Rexx  that  results  in  an 
output  of  the  strings  defined  as  a  user  entry  prompt  when  PULL  is 
executed. 
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SIGNAL  ON  indicates  that  the  error  condition  listed  after  it  should  not 
lead  to  a  program  stop,  but  to  an  equivalent  label  in  the  program.  By 
doing  this,  errors  can  be  trapped.  When  this  is  executed,  all  running  "do" 
groups  end  and  the  corresponding  Signal  flag  is  turned  off,  as  they  are  in 
the  direct  jump  command  using  "SIGNAL  Label".  After  error  handling 
you  are  unable  to  continue  the  program,  instead  you  must  address  a 
defined  entry  point.  Special  system  variables  contain  the  line  number 
(SIGL)  after  interrupt  conditions,  or  in  this  case  the  error  code  or  the 
return  code.  The  use  of  these  variables  becomes  clear  in  the  two  blocks 
at  the  end  of  the  program.  ERRORTEXT()  is  a  built-in  Rexx  function 
that  outputs  an  appropriate  (English)  text  for  a  given  Rexx  error  number. 

PARSE  transmits  character  strings  to  variables.  It  also  offers  a  powerful 
and  simple  procedure  for  string  manipulation  and  cutting. 

Although  PARSE  PULL  waits  for  an  entry  from  the  console,  there  is  no 
capitalization  of  the  entry,  as  in  the  PULL  command. 

INTERPRET  is  a  very  simple  but  powerful  command.  The  expression  that 
follows  is  simply  executed  as  a  Rexx  command. 

Experiment  with  this  program;  it  quickly  gives  you  an  understanding  of 
how  Rexx  works. 
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5.    ARexx  Syntax 


ARexx  programs  can  contain  all  ASCII  symbols.  Either  uppercase  or 
lowercase  letters  can  be  used,  since  all  symbols  are  automatically 
converted  to  capital  letters. 

An  ARexx  program  must  begin  with  a  comment.  The  interpreter  then 
searches  for  a  clause,  usually  a  single  line,  that  is  delimited  by  a  semicolon 
(;),  keywords  or  a  colon  (after  an  individual  character).  The  tokens 
contained  in  the  clause  are  then  evaluated  from  left  to  right. 


5.1      Using  Tokens 


Tokens  are  the  smallest,  self-contained  units  in  the  language,  such  as 
words  in  a  sentence.  They  are  separated  by  empty  spaces  (or,  for 
operators,  by  their  parameters).  The  interpreter  differentiates  among 
comments,  symbols,  strings,  operators,  and  special  characters. 


5.1.1  ARexx  Symbols 


Symbols  are  characters  (A..Z,  a..z,  0..9),  .!?$#@  and  _  (Underscore). 
Alphabetical  characters  that  appear  in  a  symbol  are  converted  to  capital 
etters.  There  are  four  types  of  symbols: 

Constants  begin  with  a  number  or  a  decimal  point. 

Simple  variables  do  not  begin  with  a  number  and  do  not  contain  a 
period. 

Stem  are  like  simple  variables,  but  have  a  period  at  the  end. 

Compound  variables  begin  with  a  stem,  followed  by  one  or  several 
constants  or  simple  variables,  each  delimited  by  a  period.  The  value 
of  a  constant  symbol  (that  is  not  necessarily  a  number)  is  the  name 
of  the  symbol,  in  capital  letters.  Other  symbols  are  variables.  They 
can  be  assigned  a  value  during  the  program  run.  If  a  variable  has 
not  been  given  a  value,  it  is  an  uninitialized  variable  and  acts  as  a 
constant;  its  value  is  then  its  capitalized  name.  For  example: 
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47.11  /*  a  constant  */ 

7NewYorkers  /*  a  constant,  but  not  a  number. 
=>  7NEWY0RKERS  */ 

Field.  /*  a  stem  symbol  */ 

Field. 3 .Where?/*  a  compound  variable  */ 


Stems  and  compound  variables  have  special  qualities  that  enable  unusual 
programming  techniques.  The  structure  of  a  compound  variable  is 
"stem.nl. n2....ni".  The  name  before  the  first  period  is  the  stem  symbol  and 
every  other  element,  from  "nl"  to  "ni",  is  either  a  constant  or  a  simple 
variable.  Whenever  the  interpreter  finds  a  compound  variable,  the 
elements  in  it  are  evaluated.  These  strings  can  contain  any  characters, 
even  spaces,  and  are  not  converted  to  capital  letters.  A  new  variable 
name  is  created  and  its  contents  are  then  calculated.  For  example,  if  "X" 
has  the  value  5  and  "Y"  has  the  value  2,  then  "a.x.y"  creates  the  new 
name  "A.5.2".  By  using  the  stem  you  can  call  or  initialize  an  entire  group 
of  variables.  If  a  stem  is  assigned  a  value,  all  combined  variables  that 
contain  the  stem  also  receive  the  same  value. 

Compound  variables  can  also  be  used  as  addressable  arrays  or  stacks. 
For  example,  if  you  wanted  to  show  the  area  code  of  a  city  with  the  city 
name,  you  could  create  two  fields  "CITY"  and  "AREACODE".  Paired 
values  would  be  stored  with  the  same  index.  The  field  "CITY"  would  be 
searched  for  the  desired  entry  and  "San  Francisco"  would  be  found  with 
the  index  "415".  In  this  case,  "AREACODE.415"  would  contain  the 
appropriate  area  code.  In  Rexx  you  can  take  another  approach:  the 
variable  "CITY"  could  contain  the  name  of  the  desired  place  and 
"AREACODE.CITY"  would  evaluate  into  "AREACODE.SanFrancisco", 
which  would  lead  directly  to  the  desired  number.  Although  this  process 
offers  faster  access  to  the  data,  it's  not  reversible.  You  cannot  use  the 
same  field  to  look  for  the  city  name  by  area  code,  which  is  possible  with 
the  first  method. 
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5.1.2  Character  Strings  in  ARexx 

Strings  are  character  strings  that  begin  and  end  with  quotation  marks  ("). 
The  quotation  mark  itself  can  be  included  by  typing  it  twice  ("").  Single 
quotes  can  be  used  instead  of  quotation  marks.  Strings  must  be  written 
on  one  line  only.  Empty  character  strings  are  called  "null  strings".  A 
string  followed  by  an  open  parenthesis  "("  is  assumed  to  be  a  function 
name.  An  "x"  or  "b"  immediately  following  indicate  hexadecimal  or 
binary  evaluation  of  the  string.  In  this  case,  only  the  characters  (0..9  and 
a..f  for  "x"  and  0  or  1  for  "b")  can  be  contained  in  the  string.  (Empty 
spaces  can  be  used  to  make  the  program  readable.)  Such  character 
strings  are  immediately  converted  into  strings  with  the  equivalent  ASCII 
symbols.  Enter  control  codes  or  memory  addresses  in  this  way.  For 
example: 


■  Is  there  a  grammar ' 

/* 

simple  example  */ 

"Is  it  possible..." 

/* 

=>  Is  it  possible... 

n  ii 

/* 

Null-String*/ 

"Say  ""It  is  true"" !" 

/* 

=>  Say  "It  is  true"! 

"49  42  4d"x 

/* 

big  blue  in  hex*/ 

"00110000"b 

/* 

binary  for  ASCII  0*/ 

5.1.3  The  ARexx  Operators 


Operators  are  the  characters  ~+-*/=x&lA.  Empty  spaces  (even  between 
them)  make  no  difference  to  the  ARexx  interpreter.  The  space  character 
itself,  placed  between  symbols  or  strings,  is  an  operator.  The  execution  of 
operators  has  a  set  order.  Operators  with  equal  priority  are  executed  from 
left  to  right. 
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Operator 

Priority 

Meaning 

+ 

8 
8 

logical  negation 
prefix:  conversion 

** 
* 

/ 

8 
7 
6 
6 

prefix:  negation 
exponentiation 
multiplication 
division 

% 
II 

6 
6 

integer  division 
remainder 

+ 

5 

addition 

- 

5 

subtraction 

II 

4 

concatenation 

(space) 

> 
< 

4 
3 
3 
3 
3 
3 
3 
3 

concatenation  with  empty  space 

exact  equality 

exact  inequality 

normal  equality 

normal  inequality 

greater  than 

greater  than  or  equal 

less  than 

& 
1 

3 
2 
1 
1 

less  than  or  equal 
logical  AND 
logical  OR 
logical  exclusive  OR 

5.1.4  ARexx  Special  Characters 

The  special  characters  ";,:()"  also  have  meaning.  For  example: 


semicolonC)  A  semicolon  separates  individual  clauses.  Normally,  this 
is  indicated  by  a  line  feed.  Semicolons  are  used  to  put 
several  clauses  on  one  line. 

commaO  A  comma  prevents  the  automatic  semicolon,  if  a  clause 

extends  over  several  lines.  (Commas  also  separate  the 
arguments  of  a  function  call  from  one  another.) 

colon(:)  If  there  is  a  symbol  in  front  of  a  colon,  a  branching 

(Label)  is  defined.  A  colon  also  implies  a  semicolon. 

parentheses(O)  A  single  open  parenthesis,  directly  following  a  symbol, 
forces  interpretation  of  the  clause  as  a  function  name. 
Closed  parentheses  also  form  expression  groups.  This  is 
used  to  alter  the  regular  operator  priority. 
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5.2      Expressions 


Expressions  consist  of  one  or  several  terms,  with  or  without  operators. 
They  can  be  strings,  symbols,  or  function  calls,  perhaps  grouped  with 
parentheses.  Between  a  pair  of  terms,  there  is  always  a  dyadic  element. 
There  can  be  one  or  several  prefix  operators  affecting  the  term.  Strings 
are  always  interpreted  as  character  strings,  as  are  constant  symbols 
(converted  into  capital  letters).  Variable  symbols  are  replaced  with  their 
contents,  or  regarded  as  constant  symbols.  Function  calls  are  recognized 
by  an  open  parenthesis,  followed  by  a  symbol. 

Arguments  contained  in  parentheses  are  evaluated  and  passed  to  the 
function  in  place  of  the  arguments.  The  calculated  value  is  returned. 

The  value  of  an  expression  is  determined  in  order  by  parentheses  and 
operator  priority.  First  the  symbols  that  are  contained  in  it  are  replaced. 
For  example: 


fak(n)  "is  the  factorial  of"  n 


This  expression  consists  of  the  function  call  "fak("  with  the  argument 
expression  "n",  a  concatenation  operator  (concatenation  with  empty 
spaces),  the  string  "is  a  factorial  of,  a  further  chain,  and  the  variable 
symbol  "n". 

First,  the  interpreter  determines  the  function  argument  and  then  calls  the 
function.  The  function,  if  it's  not  defined  as  a  procedure,  can  assign  a  new 
value  to  the  variable  "n".  At  the  second  occurrence  of  "n",  another 
content  is  calculated.  The  order  of  evaluation  does  not  affect  the 
calculation  here,  only  its  position.  In  short,  symbols  are  always  evaluated 
from  left  to  right  and  replaced  by  the  resulting  value.  If  there  is  a  function 
call,  it's  executed  first,  then  the  symbol  value  replacement  process 
resumes.  After  this,  the  expression  is  evaluated  under  the  priority  rules.  If 
the  operator  priority  ranking  is  equal,  an  evaluation  order  is  not  defined. 
So,  the  analysis  moves  from  left  to  right,  as  the  Rexx  language  definition 
implies  (and  algebraic  rules  state  and  programmers  expect).  Exceptions  to 
the  rule  have  not  been  observed. 

Both  sides  of  logical  operators  are  always  evaluated,  even  if  the  result  is 
already  clear: 
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(2=2)     I     (120   =   fak(5)) 


For  example,  "fak("  is  always  fully  executed,  even  if  analysis  has  already 
determined  that  the  result  of  the  procedure  is  1 . 

Operators  can  be  divided  into  four  groups:  arithmetic,  concatenation, 
comparison,  and  logical  operators. 


5.2.1  Arithmetic  Operators 


Prefix  conversion  (+) 

This  operator  acts  as  a  prefix.  The  given  number  is 
converted  to  internal  notation,  rounded,  and  formatted 
according  to  the  NUMERIC  settings. 

"    12.34    "  ==>    '12. 34" 

"2.0009  ==>    '2.001'     (with   DIGITS=3) 

Prefix  negation  (-) 

The  single  negation  prefix  changes  the  sign  of  the 
operand.  It  also  has  the  same  effects  as  the  prefix  for 
conversion  (+). 

-"    7.23    "  ==>    '-7.23' 

-3E3  ==>    '-3000' 

Exponentiation  (**) 

The  left  operand  (base)  is  evaluated  as  the  exponent  of 
the  right  operand  (exponent).  The  exponent  must  be  an 
integer.  The  number  of  decimal  places  (for  positive 
exponents)  is  the  product  of  the  exponent  and  the 
number  of  places  given  after  the  decimal  point  in  the 
base  number. 

2**8  ==>   256 

4**-l  ==>   0.25 

0.1**3  ==>   0.001 

Multiplication  (*) 

Calculates  the  product  of  the  terms  to  the  left  and  right 
of  the  operand.  The  number  of  decimal  places  is 
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determined  by  the  sum  of  the  decimal  places  in  the  two 
terms. 


4*7 
0.5*1.50 


=>   49 

=>   0.750 


Division  (/) 


Determines  the  quotient  of  the  two  numbers.  The 
number  of  decimal  places  is  as  large  as  necessary,  and 
can  be  limited  by  the  setting  of  NUMERIC  DIGITS. 


8/4 
8/3 


==>   2 

==>   2.667    (with  DIGITS=3) 


Integer  division  (%) 

Calculates  the  quotient  of  two  numbers.  The  integer 
portion  of  the  result  is  returned. 


8%3 


==>   2 


Remainder  (//)  Returns  the  remainder  of  an  integer  division  of  the 
dividend  terms.  To  determine  the  remainder  of  "a//b", 
"a-(a%b)*b"  is  calculated. 


8//5 

-7//3 
3.7//0.2 


==>    3 
==>    -1 
==>    1 

Addition  (+) 


Calculates  the  sum  of  two  terms.  The  number  of  decimal 
places  in  the  result  is  determined  by  the  higher  number 
of  decimal  places  in  one  of  the  terms. 


3  +  15 

==>    18 

2.7+2.04 

==>   4.74 

Subtraction  (-) 

Calculates  the  difference  between  two  terms.  As  in 
addition,  the  number  of  decimal  places  is  determined  by 
the  higher  number  of  places  in  one  of  the  two. 
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5.2.2  Concatenation  Operators  in  ARexx 

These  operators  combine  two  strings  into  a  new  string.  There  are  three 
such  operators: 

The  explicit  concatenation  operator  (II)  connects  two  strings 
without  an  empty  space. 

-BE"  I  I  "TA"  ==>    BETA 

•  The  direct  concatenation  operator,  for  example,  a  symbol  and  a 
string,  specified  right  after  one  another.  This  results  in  a  chain 
without  an  empty  space. 

be"TA"  ==>   BETA 

•  The  null  concatenation  operator  is  when  two  strings  are  specified 
with  one  or  more  spaces  between  them;  an  empty  space  is  inserted 
between  them  in  the  concatenation. 

"with"  "empty"  "space"  ==>  with  empty  space 

5.2.3  Comparison  Operators  in  ARexx 

The  are  three  different  comparison  modes: 

•  Exact  includes  empty  spaces;  strings  of  different  length  are  never 
equal  in  exact  comparison. 

•  String  comparison  disregards  leading  spaces  and  adds  trailing 
spaces  to  fill  a  shorter  string  to  equivalent  length. 

•  Numeric  transforms  the  operands  to  numeric  notation,  using  the 
setting  of  NUMERIC  DIGITS  to  determine  the  number  of  decimal 
places.  Then  an  arithmetic  comparison  is  made  and  NUMERIC 
FUZZ  sets  the  specificity  of  that  calculation. 

With  the  exception  of  the  exact  equality  and  inequality  operators,  all 
comparison  operators  automatically  differentiate  between  numeric  and 
string  comparisons. 

If  both  terms  are  valid  numbers,  a  numeric  comparison  is  made;  otherwise 
it  is  assumed  to  be  a  string  comparison. 
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All  comparison  operators  output  a  Boolean  truth  value:  0  for  false  or  1 
for  true.  The  comparisons  ">",  "<",  ">="  and  "<="  are  used  for  strings,  as 
defined  in  the  ASCII  code.  This  means: 


"A"<"B"    ==>    1 
■A'<'a'    ==>   1 


5.2.4  Using  Logical  Operators 


All  four  logical  operators  require  two  Boolean  operators  (a  0  or  1)  and 
return  a  Boolean  result.  These  operators  cannot  be  used  for  bit-level 
logical  combinations.  (For  such  purposes,  use  the  built-in  BITxxx() 
functions.) 

Logical  NOT  (~) 

Inversion:  0  becomes  1  and  1  becomes  0. 

Logical  AND  (&) 

Returns  a  1  if  both  operators  are  true. 

Logical  inclusive  OR  (I) 

Returns  a  1  if  one  of  the  operators  is  true. 

Logical  exclusive  OR  (A  or  &&) 

Returns  a  1  if  one  of  the  operators  (not  both)  is  true. 
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5.3     ARexx  Clauses 


Clauses  are  the  smallest  executable  units  of  the  Rexx  language.  They  can 
be  divided  into  five  groups: 


5.3.1  Null  Clauses 


Lines  that  consist  of  empty  space  or  comments  are  null  clauses.  They  are 
also  formed  if  two  semicolons  follow  one  another.  These  clauses  are 
ignored  by  Rexx. 

Comments  are  character  strings  of  one  or  more  lines  that  are  contained  in 
"/*"  and  "*/";  they  can  be  set  inside  one  another,  but  must  appear  in  pairs 
(which,  in  ARexx,  do  not  have  to  appear  on  one  line).  They  hardly  affect 
execution  speed  and  can  be  used  liberally.  A  first  run  through  the 
interpreter  removes  them  and  their  function  is  taken  by  an  empty  space. 


5.3.2  ARexx  Label  Markers 


A  symbol  immediately  followed  by  a  colon  is  a  label  marker.  (The  colon 
also  implies  a  semicolon  here.)  Such  markers  serve  as  targets  for  CALL 
and  SIGNAL  commands  and  internal  function  calls.  Several  markers  can 
follow  one  another. 

If  the  same  label  marker  appears  twice  in  a  program,  only  the  first  is 
located. 


5.3.3  Assignments  in  ARexx 


A  variable  symbol  followed  by  an  equal  sign  (=)  is  an  assignment  clause. 
In  this  case,  the  operator  does  not  have  its  normal  comparison  function, 
instead  it  becomes  an  assignment  operator.  The  terms  to  the  right  of  the 
equal  sign  are  analyzed  as  an  expression  and  the  result  becomes  the 
content  of  the  variable  symbol  on  the  left. 
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5.3.4  ARexx  Commands 


A  clause  that  starts  with  a  command  keyword  is  a  command  clause.  Often 
a  single  command  represents  an  executable  action,  or  several  commands 
(for  example,  SELECT  groups)  are  combined  to  form  clauses.  They  are 
not  syntactically  complete  until  all  necessary  commands  are  available. 


5.3.5  Commands 


An  expression  that  cannot  be  assigned  to  any  other  type  of  clause  is 
assumed  to  be  external  commands.  The  expression  is  then  analyzed  and 
the  result  is  passed  to  the  specified  external  environment.  The  address 
can  be  an  external  application  (for  example,  an  editor)  or  DOS 
("COMMAND"). 
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6.    Instructions 


Instructions  consist  of  one  or  more  words  that  are  recognized  as  a  key 
word.  The  keyword  must  appear  as  the  first  token  in  the  clause.  It  cannot 
be  preceded  by  a  colon  (:),  it  would  then  be  a  label,  or  an  equal  sign  (=), 
which  indicates  a  variable.  Some  key  words  call  for  further  parameters  of 
sub-keywords.  We  don't  recommend  that  you  define  a  variable  "SAY"  or 
a  function  "NUMERIC"  because  the  readability  of  your  program  can 
suffer. 

I/O  Instructions  Control  Instructions 

ARG  ADDRESS 

ECHO  CALL 

PARSE  DROP 

PULL  INTERPRET 

PUSH  NUMERIC 

QUEUE  OPTIONS 

SAY  PROCEDURE 

SHELL 

Structural  trace 

Instructions  upper 

BREAK 

DO 

ELSE 

END 

EXIT 

IF 

ITERATE 

LEAVE 

NOP 

OTHERWISE 

RETURN 

SELECT 

SIGNAL 

THEN 

WHEN 
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6.1      I/O  Instructions 


rsRG 


Represents 
section. 


'PARSE  UPPER  ARG".  For  more  information,  see  that 


IECHO 


An  ARexx  synonym  for  SAY.  For  more  information,  see  that  section. 
|  PARSE 


] 


Syntax:  PARSE   [UPPER]    source    [template] [.template. .. ] 

Function:  In  Rexx,  PARSE  is  the  main  input  instruction.  It  takes  data 
from  various  sources  and  passes  it  on  to  one  or  several 
variables,  efficiently  parsing  character  strings.  The  effect  of 
the  input  character  string  can  be  selected  using  the 
following  sub-keywords: 

ARG  Character  strings  passed  to  the  program  at  the  call  or 

function  are  parsed.  Each  program  usually  receives  one 
string;  functions  are  capable  of  receiving  up  to  15, 
separated  by  commas,  that  are  then  parsed  out  according  to 
templates. 

EXTERNAL  An  entry  is  read  into  the  function  from  "stderr".  If  "stderr"  is 
not  defined,  the  function  returns  the  null  string. 

NUMERIC  Current  settings  of  NUMERIC  are  received  as  a  string  in 
the  following  order:  DIGITS,  FUZZ  and  FORM,  each 
separated  by  an  empty  space. 

PULL  Reads  a  string  from  "stdin",  that  is  usually  input  from  the 

keyboard.  If  nothing  is  found  in  "stdin",  program  execution 
halts  until  something  is  entered.  The  function  QUEUED  can 
query  how  many  lines  have  been  saved  in  "stdin". 

SOURCE  Returns  a  string  of  data  on  how  the  program  was  called,  in 
the  form  "{COMMANDIFUNCTION}  {011}  Type  Result 


496 


6.1  I/O  Instructions 


Called  Resolved  Ext  Host".  The  first  word  signals  whether 
the  call  is  a  program  or  a  function.  Then  a  Boolean  value 
indicates  whether  a  result  string  has  been  requested. 
"Called"  is  the  name  with  which  the  program  was  invoked, 
"resolved"  is  the  full  path  and  file  extension  of  the  program 
(usually  ".rexx").  "Host"  is  the  initial  host  address  for 
external  commands. 

VALUE  expression  WITH 

An  expression  that  calls  for  the  sub-keyword  WITH.  An 
expression  is  evaluated  and  the  result  is  used  as  the  parse 
input  string.  The  keyword  "WITH"  is  used  to  separate  the 
expression  and  the  template. 

VAR  Variable 

The  values  of  the  given  variables  are  used  as  the  parse 
input  sting.  If  several  templates  are  entered,  the  current 
value  of  the  variable  is  taken  each  time.  (It  can  also  change 
if  the  same  variable  appears  in  the  template.) 

VERSION  Returns  a  string  in  the  form  "ARexx  Version  CPU  MPU 
Video  Freq".  The  value  of  "Version"  is  the  interpreter 
revision  (i.e.  "V1.21"),  "CPU"  is  the  processor  type 
("680x0"),  and  "MPU"  is  the  math-coprocessor  ("6888x",  if 
present,  otherwise  "NONE").  "Video"  returns  to  video 
system  ("PAL"  or  "NTSC")  and  "Freq"  returns  the  network 
frequency  ("50HZ"  or  "60HZ"). 

The  UPPER  keyword  forces  a  translation  of  the  source  data  into  capital 
letters  and  it's  used  before  the  keyword,  which  indicates  the  source. 

Templates  can  be  assembled  from  symbols,  strings,  operators  or 
parentheses.  The  function  parses  source  strings  into  sub-strings  that  are 
assigned  to  the  symbols  in  the  template.  The  process  ends  when  all 
variables  have  been  assigned  values.  If  a  source  string  is  completely 
evaluated,  before  all  listed  variables  obtain  a  new  value,  the  remaining 
variables  are  assigned  the  null  string.  There  are  three  important  template 
functions: 
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Parsing  by  words 

If  the  variable  names  follow  directly  after  one  another  delimited  only  by 
an  empty  space,  the  source  string  is  parsed  (using  the  spaces)  into  words, 
each  of  which  is  assigned  to  the  next  available  variable.  The  last  variable 
receives  the  remainder  of  the  string.  A  period  (.)  can  be  used  as  a  "place- 
holder" in  a  template,  acting  like  a  variable,  but  not  actually  receiving  the 
corresponding  part  of  the  string.  For  example: 

/*  VERSION  returned: "ARexx  VI. 15  68030  68882  PAL  50HZ"  */ 
parse  version  .  Revision  CPU  MPU  . 
say  Revision  CPU  MPU 

In  this  example  the  first  word  "ARexx"  is  not  informative;  it  is  to  be 
deleted  and  so  a  period  appears.  After  the  parse  is  executed,  the  variable 
"Revision"  contains  "  VI. 15",  CPU  the  value  "68030"  and  MPU  is 
"68882".  The  rest  of  the  source  string  is  uninteresting;  it  is  absorbed  by 
the  second  period,  same  as  the  first  word. 

Parsing  by  position 

Absolute  or  relative  positions  of  individual  elements  of  the  source  strings 
can  be  specified  using  numeric  values,  between  the  symbols.  Relative 
positions  are  differentiated  from  absolute  positions  by  their  prefixes 
(monadic  "+"  or "-"  operators).  For  example: 

Test  =  "1234567890" 

parse  var  Test  3  a  5  b  +3  4  c 

say  a  b  c  /*  =>  34  567  4567890  */ 

Parsing  by  pattern 

If  elements  of  the  source  string  are  separated  by  keywords  or  other 
specific  characters,  these  can  be  searched  and  the  parsing  will  follow  the 
"pattern  markers."  The  function  also  removes  markers  it  finds  from  the 
source  string;  this  means  the  string  is  changed  during  a  pattern  parse.  An 
example: 

/*  The  program  was  called  with  the  argument  "DRIVE  dhO:  name  Bingo".*/ 
parse  arg  "DRIVE"  Drive  "NAME"  Name 
say  Drive  name 

/*  =>  dhO:  Bingo*/ 
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See  also:       ARG,  PULL,  UPPER 


I  PULL 


PULL  is  short  for  "PARSE  UPPER  PULL".  For  further  information,  see 
that  section. 


I  PUSH 


Syntax:         push  [expression] 

Function:  PUSH  prepares  input  lines  for  another  program  that  expects 
entry  from  "stdin".  During  the  function,  a  "Return"  (ASCII 
13)  is  attached  to  "expression"  and  the  result  is  stored  in 
the  "stdin"  channel  along  the  "LDFO  principle"  (Last  In  First 
Out).  The  last  line  stored  with  PUSH  is  the  first  read  from 
"stdin".  The  number  of  lines  waiting  in  "stdin"  can  be 
queried  with  the  function  QUEUED. 

Caution:  This  instruction  should  only  be  used  with  interactive  DOS 
devices  that  are  driven  by  a  DOS  handler  that  supports  the 
"ACTION_STACK"  instruction  (or  CON:,  PIPE:,  and  similar 
input).  This  is  especially  important  if  you  are  attempting 
data  redirection. 


See  also: 
IQUEUE 


QUEUE,  QUEUEDO 


Syntax:         queue   [expression] 

Function:  QUEUE  prepares  input  lines  for  another  program  that 
expects  entry  from  "stdin".  The  value  of  "expression"  is  a 
single  "Return"  (ASCII  13);  the  result  is  stored  in  the  "stdin" 
channel  along  the  "FIFO  principle"  (First  In  First  Out).  The 
first  line  stored  with  QUEUE  is  also  the  first  read  from 
"stdin".  The  number  of  previously  stored  lines  in  "stdin"  can 
be  queried  with  the  function  QUEUED. 

Caution:  This  instruction  should  only  be  used  with  interactive  DOS 
devices  that  are  driven  by  a  DOS  handler  with  an 
"ACTION_QUEUE"  instruction  (or  CON:,  PIPE:,  and  others 
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like  them).  This  is  important  for  scripts  involving  input 
redirection. 


See  also:       PUSH,  QUEUED() 


^AY 


Syntax:         say   [expression] 

Function:  The  value  of  "expression"  receives  a  single  "Return"  (ASCII 
13)  and  is  written  to  "stdout",  which  is  usually  the  monitor, 
and  displayed  there. 
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6.2     Structured  Instructions 

[BREAK  I 

BREAK  is  only  allowed  within  DO  instructions.  For  more  information  see 
that  section. 

IPO  I 

Syntax:  do   [Iteration]    [Condition] 

[Instructions] 
END   [Symbol] 

DO  is  used  to  group  instructions  together  and  possibly  execute  them 
again.  The  iteration  takes  the  form: 

[Symbol=ExprI]    [TO  ExprT]     [BY   ExprB]  ]     [FOR   ExprF] 
or :    ExprR 
or :    forever 

All  expressions  that  appear  in  the  instruction  must  result  in  a  number. 
ExprR  and  ExprF  must  be  positive  integers.  The  key  words  BY,  TO,  and 
FOR  can  appear  with  a  matched  expression  (that  is  analyzed  once  at  the 
beginning)  in  any  order. 

•  The  formal  element  "Symbol=ExprI"  defines  a  run-time  variable  and 
supplies  an  initial  value  to  it.  It  must  follow  the  key  word  DO. 

•  BY  ExprB:  Determines  the  increment  added  to  running  variables 
with  each  iteration.  If  BY  is  not  specified,  it  is  assumed  to  be  1. 

•  TO  ExprT:  Sets  the  upper  limit  (or  lower  limit,  depending  on  the 
increment)  of  the  run-time  variable.  If  this  limit  is  overstepped 
during  an  iteration,  the  loop  terminates  and  the  program  continues 
at  the  corresponding  END. 

•  FOR  ExprF:  Specifies  the  maximum  number  of  repetitions.  When 
this  value  is  reached,  the  DO  loop  terminates,  regardless  of  the  value 
of  a  run-time  variable.  If  all  you  need  is  to  specify  the  number  of 
repetitions,  you  can  use  the  ExprR  form. 

•  FOREVER:  If  you  do  not  need  an  index  variable,  this  key  word 
ensures  repetition.  This  kind  of  loop  ends  with  a  LEAVE  or 
BREAK.  For  example,  the  condition  can  read: 
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WHILE  ExprW 

or:  UNTIL  ExprU 


ExprW  and  ExprU  must  return  "0"  or  "1". 

WHILE  ExprW:  This  expression  is  evaluated  at  the  beginning  of 
each  iteration.  If  it  returns  a  "1",  the  loop  continues;  a  "0"  terminates 
it. 

•  UNTIL  ExprU:  Has  the  same  function  as  WHILE,  but  with  reverse 
logic.  If  it's  a  "0",  the  loop  is  terminated;  if  it's  a  "1",  the  loop 
continues. 

The  DO  group  is  closed  with  the  END  instruction,  after  which  a  counting 
variable  can  be  specified.  This  is  helpful  for  debugging,  since  nesting 
errors  during  DO  loops  can  be  recognized  by  the  interpreter.  It  also 
improves  program  readability. 


Structural  instructions  in  DO  groups 

BREAK,  LEAVE  [Symbol],  ITERATE  [Symbol]. 


BREAK  terminates  the  inside  DO  group.  Program  execution  continues 
after  moving  to  the  corresponding  END.  This  is  also  the  action  an 
INTERPRET  instruction  forces  in  implicit  DO  groups. 

In  contrast,  LEAVE  is  only  allowed  in  DO  loops.  LEAVE  terminates  the 
inside  DO  group  and  execution  continues  after  the  corresponding  END. 
A  variable  can  be  set  here  to  terminate  several  embedded  DO  loops 
simultaneously,  if  your  run-time  variable  is  controlled  in  one  of  the  outer 
loops. 

ITERATE  does  not  terminate  the  DO  loop,  but  rather  jumps  back  to  the 
top  of  it.  The  value  determined  with  BY  is  added  to  the  run-time  variable, 
all  conditions  are  evaluated  and,  if  appropriate,  the  next  iteration  starts. 
The  variable  specified  after  ITERATE  acts  analogously  to  the  variable 
function  in  LEAVE. 

|  ELSE  ~~| 

ELSE  is  only  valid  within  an  IF  instruction.  For  further  information,  see 

that  instruction. 
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ffiND 


] 


END  is  an  element  of  DO  and  SELECT  groups.  For  more  information,  see 
that  section. 


I  EXIT 


See  also: 

EE 


] 


Syntax:         exit   [expression] 

Function:  This  instruction  terminates  the  program  where  it  is  read  and 
passes  (if  indicated)  a  return  value  to  the  calling  program.  If 
a  return  string  is  requested,  the  result  of  "expression",  a 
character  string,  is  stored  in  the  allocated  storage  block  and 
a  pointer  to  that  block  is  set  to  RESULT_2.  If  no  string  was 
requested  and  the  program  was  running  as  an  instruction, 
EXIT  tries  to  evaluate  the  result  of  "expression"  with  INT 
and  report  it  as  the  return  code.  The  EXIT  instruction 
(without  a  return  value)  is  also  implied  by  the  end  of  a 
program. 


RETURN 


Syntax:  if  expression 

THEN  command 
[ELSE  command] 

Function:  The  IF  instruction  conditionally  executes  instructions.  The 
expression  after  IF  must  return  a  Boolean  result,  a  "0"  or 
"1".  If  it's  a  "1",  the  instruction  (or  DO  group)  named  after  it 
is  executed.  If  the  expression  is  "0",  the  instruction  behind 
ELSE  is  executed,  if  ELSE  was  specified. 

An  ELSE  clause  always  refers  to  the  last  IF.  Nested  IF  instructions  make 
it  impossible  to  use  one  of  these  branches.  In  this  case,  a  dummy 
instruction  (NOP)  restores  access  to  the  next  higher  IF  instruction.  Just 
indicating  an  empty  clause  by  typing  two  semicolons  is  not  enough  in 
Rexx,  as  it  is  for  other  programming  languages.  For  example: 


if  1+1=2  then 
if  2+2=4  then 


/*  outer  IF  */ 
/*  inner  IF  */ 


503 


6.  Instructions 


say  "The  world  is  still  alright." 

else  NOP  /*  belongs  to  the  inner  IF  */ 

else  say  "Nothing  is  happening  anymore!"    /*  belongs  to  the  outer  IF  */ 

See  also:       NOP 
I  ITERATE  I 

ITERATE  is  only  applicable  within  DO  loops.  For  more  information,  see 
that  description. 


I  LEAVE 


LEAVE  is  only  applicable  within  DO  loops.  For  more  information,  see 
that  section. 

I  NOP  ~l 

Syntax:         nop 

Function:  Basically,  "No  OPeration"  is  a  dummy  instruction  that  does 
nothing.  The  instruction  takes  on  meaning  during  IF 
instructions;  it  has  no  other  function. 

I  OTHERWISE  ~i 

OTHERWISE  is  part  of  the  SELECT  instruction.  For  more  information, 
see  that  section. 


I  RETURN 


Syntax:         return   [expression] 

Function:  Used  to  end  one  function  and  continue  program  execution 
where  it  was  called.  "Expression"  is  analyzed  and  the  result 
is  the  returned  value  of  the  function.  Functions  called  from 
within  an  expression  must  return  a  result,  or  an  error 
message  appears.  Placing  a  RETURN  in  the  main  program  is 
not  an  error,  it  is  equivalent  to  EXIT. 

See  also:       EXIT 
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I  SELECT 


Syntax:         select 


WHEN  expression  [ ; ]  then  [ ; ]  command 

[OTHERWISE  [;]  [Instructions]] 
END 


Function:  The  SELECT  instruction  is  used  to  make  a  choice  among 
several  different  possibilities.  After  it,  a  series  of  WHEN 
constructions  can  follow,  each  of  which  must  contain  an 
expression  that  returns  a  Boolean  result,  and  a  instruction 
(or  DO  group)  that  is  to  be  executed  if  the  result  of  the 
expression  is  "1".  But  only  the  first  WHEN  group  whose 
Boolean  expression  returns  a  1  is  executed.  If  none  of  the 
expressions  are  true,  instructions  behind  the  key  word 
OTHERWISE  are  executed.  This  can  comprise  an  entire  list 
of  instructions.  OTHERWISE  and  END  shape  a  simple  DO 
group  in  this  respect. 

The  OTHERWISE  construction  is  not  required  in  a 
SELECT  instruction.  If  no  WHEN  construction  is  executed, 
it's  either  called  or  an  error  message  appears. 


I  SIGNAL 


] 


Syntax: 


Function: 


SIGNAL  {ON  I  OFF}  Condition 

or:  SIGNAL  {  [VALUE]  expression 


Label   } 


There  are  two  basic  forms  of  the  SIGNAL  instruction.  The 
first  is  used  to  switch  error  trapping  flags  on  and  off.  The 
second  is  an  expression  used  to  transfer  control;  this  one  is 
evaluated.  A  control  transfer  should  be  used  sparingly.  It  is 
primarily  useful  for  resuming  the  program  at  a  defined 
location  after  an  error  condition. 


Error  interrupts  make  it  possible  to  recognize  error 
conditions  that  would  otherwise  lead  to  program 
termination,  and  perhaps  to  catch  them  before  they  do.  If 
"SIGNAL  ON  condition"  is  used  to  activate  a  specific  error 
interruption,  the  program  is  not  stopped,  instead  it  branches 
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ITHEN 


to  a  label  indicated  by  the  key  word  of  the  corresponding 
condition.  The  following  key  words  are  available: 

BREAK.C  fctriWcl:  Break  has  occurred. 

BREAK_D  [ctrlhfDl:  Break  has  occurred. 

BREAK_E  |ctri|4H:  Break  has  occurred. 

BREAK.F  [ctnl+fFl:  Break  has  occurred. 

ERRORS         The  return  code  passed  by  an  external 
program  was  not  "0". 

FAILURE        The  return  code  was  greater  than  the 
FAILAT  setting. 

HALT  A  HALT  was  encountered  (after  "hi",  for 

example). 

IOERR  DOS  has  reported  an  I/O  operation  error. 

NOVALUE       An  undefined  variable  was  called. 

SYNTAX         There  have  been  syntax  or  execution  errors. 

1 


This  is  only  used  within  IF  and  SELECT  instructions.  For  more 
information,  see  that  section. 


|  WHEN 


] 


WHEN  is  also  only  used  within  a  SELECT  instruction.  For  more 
information,  see  that  section. 
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6.3     ARexx  Control  Instructions 

[ADDRESS  | 

Syntax:  ADDRESS  {Symbol  I  string}  expression 

ADDRESS  {Symbol  I  String} 
ADDRESS  [VALUE]  expression 
ADDRESS 

Function:  ADDRESS  defines  the  target  of  an  external  command.  Its 
argument  must  provide  the  name  of  an  ARexx  message 
port,  listed  in  the  Public  Port  List  of  "exec".  The  first  form 
shown  does  not  change  the  current  setting,  it  only  sends  a 
command  to  a  certain  ARexx  port.  The  name  of  the  port  is 
specified  as  a  symbol  (that  can  be  variable)  or  a  string.  Then 
the  command  character  string  to  be  passed  to  the  external 
message  port  follows.  The  next  two  forms  of  ADDRESS  set 
a  new  target  command  host.  In  the  third  form,  the  name  of 
the  target  is  an  expression  that  must  first  be  analyzed. 

VALUE  is  only  necessary  if  the  expression  starts  with  a 
symbol  or  character  string.  The  interpreter  also  stores  the 
indicated  target;  the  last  form  of  the  examples  shown 
(without  parameters)  toggles  between  two  addresses. 

The  default  setting  is  "REXX".  The  "COMMANDS"  host  is 
a  special  target  address  (it  represents  DOS).  To  query  the 
current  setting,  use  the  internal  function  ADDRESS().  Any 
clause  that  only  contains  a  single  expression  that  the 
interpreter  cannot  manipulate  in  any  way,  is  assumed  to  be 
an  external  command  and  passed  to  the  appropriate  port. 

See  also:       SHELL,  ADDRESS() 

fCALL  | 

Syntax:  CALL  {Symbol  I  String}  [Exp.  ]  [,Exp.,...] 

Function:  Calls  an  internal,  built-in,  or  external  function.  The  function 
name  (as  a  string)  can  be  a  symbol  that  in  turn  can  be  a 
variable  or  a  character  string.  Entering  a  character  string 
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bypasses  the  internal  function  search  of  the  program.  This 
instruction  controls  functions  internal  to  the  interpreter,  or 
external  functions,  which  are  protected  from  re-definition  in 
the  running  program.  Following  CALL,  if  necessary,  one  or 
several  expressions,  separated  by  commas,  can  present 
arguments  for  the  function  (for  external  functions,  the 
maximum  number  is  15)  that  can  then  be  accessed  with 
ARC 

In  contrast  to  the  usage  of  the  direct  function  call  "Symbol 
(Arg,Arg, ...)",  which  is  analyzed  to  return  a  value 
immediately,  CALL  returns  its  result  to  the  system  variable 
RESULT.  If  no  value  results,  RESULT  remains  un- 
initialized after  the  call. 


IDROP 


Syntax:  DROP  symbol    [Symbol    . . . ] 

Function:  Variables  are  deleted  with  DROP.  They  are  placed  in  an  un- 
initialized state,  in  which  the  value  of  the  variable  is  the 
variable  name  itself.  It  is  not  a  mistake  to  use  DROP  on  a 
previously  un-initialized  variable.  If  a  stem  (a  symbol 
ending  with  a  period)  is  specified  as  the  variable  to  be 
dropped,  all  variables  that  use  this  stem  are  re-set. 

|  INTERPRET  1 

Syntax:  INTERPRET  expression 

Function:  The  result  of  "expression"  is  interpreted  as  an  ARexx 
program.  By  using  this  instruction,  entire  sections  of  the 
program  can  be  evaluated  only  when  the  program  is 
actually  run.  The  result  of  "Expression"  is  executed  as  if  it 
were  surrounded  by  an  implied  DO  ...;  END"  group. 
LEAVE  or  ITERATE  instructions  can  only  refer  to  DO 
loops  also  defined  here.  BREAK  makes  it  possible  to  leave 
the  INTERPRET  instruction  and  continue  the  program. 
Branching  instructions  in  the  expression  are  ignored  by  the 
interpreter  and  you  cannot  define  a  function  using 
INTERPRET. 
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I  NUMERIC 


Syntax:  NUMERIC  {DIGITS  I  FUZZ}  [Expression] 

NUMERIC  FORM  {SCIENTIFIC  I  ENGINEERING} 

Function:     NUMERIC  sets  the  form  of  number  representation  and  the 
precision  of  numeric  operations. 

DIGIT  [Expression] 

Sets  significant  places  in  arithmetic  operations. 
"Expression"  must  be  an  integer  between  1  and  14,  larger 
than  the  current  NUMERIC  FUZZ  setting.  Small 
adjustments  here  should  be  made  with  care,  since  all 
operations,  including  run-time  variables,  are  affected.  If 
"Expression"  is  not  included  in  the  clause,  the  default 
setting  is  9.  The  current  setting  can  be  queried  with  the 
function  DIGITS(). 

NUMERIC  FUZZ  [Expression] 

Returns  the  number  of  places  (from  the  right)  to  be 
disregarded  during  numeric  comparison  and  rounding 
operations.  "Expression"  must  evaluate  to  an  integer  from  0 
to  13  that  is  smaller  than  the  current  NUMERIC  DIGITS 
setting.  If  it's  omitted,  0  is  the  default  setting.  The  current 
setting  can  be  queried  with  the  function  FUZZ(). 

NUMERIC  FORM  (SCIENTIFIC  I  ENGINEERING} 

Determines  the  type  of  display  for  results  in  exponential 
notation.  Choices  are  the  academic  style  (with  numbers 
between  1  and  10  in  front  of  the  decimal  point),  the 
SCIENTIFIC  (default)  setting,  or  engineer's  display  in 
which  the  exponent  is  always  a  multiple  of  3.  The  current 
setting  can  be  called  with  the  function  FORM().  These 
NUMERIC  settings  are  protected  during  a  call  to  a 
function  and  set  back  after  completing  it. 

See  also:       PARSE  NUMERIC,  OPTIONS 
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|  OPTIONS 


Syntax:  options  failat  expression 

OPTIONS  PROMPT  expression 
OPTIONS  [NO  ] CACHE 
OPTIONS  [NO  ] RESULTS 
OPTIONS 

Function:  OPTIONS  is  the  general  instruction  to  set  various  default 
settings  in  the  interpreter. 

FAILAT  Expression:  Sets  the  limit  after  which  return  codes  lead  to  a 
FAILURE  report.  The  default  setting  is  the  FAILAT  setting 
in  the  calling  program  (normally  10).  "Expression"  must 
return  a  positive  integer  value. 

PROMPT  Expression 

Sets  a  character  string  to  be  used  with  PARSE  PULL  or 
PULL  instructions  as  a  user  entry  prompt.  Normally,  there  is 
no  prompt. 

[NO  ]CACHE 

Switches  the  internal  instruction  cache  (in  the  interpreter) 
on  or  off.  This  switch,  which  increases  function  speed,  is 
normally  on. 

[NO  1RESULTS 

Tells  the  interpreter  whether  or  not  it  should  request  a 
result  string  when  it  executes  an  external  instruction. 

Use  OPTIONS  without  any  parameters  to  reset  the  default 
settings.  The  settings  you  make  with  OPTIONS  are  (such  as 
NUMERIC  settings)  secured  for  the  duration  of  function 
calls. 

|  PROCEDURE  ~| 

Syntax:  PROCEDURE   [EXPOSE  VSymbol    [VSymbol   . . . ] ] 

Function:  Used  within  an  internal  function  to  define  its  variables  (up 
to  RETURN)  as  local  variables.  The  function  then  has  no 
access  to  the  main  program  variables  unless  indicated  with 
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I  SHELL 


the  (optional)  key  word  EXPOSE.  In  the  list  that's  placed 
after  the  EXPOSE  variable  stems  or  concatenated  variables 
indicate  variables  that  remain  accessible.  In  this  case,  the 
order  of  exposure  is  important.  For  example,  the  variable  Q 
has  the  value  45  in  the  main  program.  After  "PROCEDURE 
expose  Q  RS.Q",  the  variables  Q  and  RS.45  are  still 
available  to  the  function.  If  the  instruction  had  been  given 
as  "PROCEDURE  EXPOSE  RS.Q  Q",  then  RS.Q  and  Q 
would  be  exposed.  Concatenated  variables  are  evaluated 
from  left  to  right. 


J 


SHELL  is  an  ARexx  synonym  for  ADDRESS.  For  more  information,  see 
that  section. 


ITRACE 


Syntax:  TRACE  [Symbol  I  String  I  [VALUE]  Expression] 

Function:      The  TRACE  instruction  controls  running  ARexx  programs 
and  is  most  often  used  for  error  analysis. 

Since  you  usually  have  to  enter  this  instruction  by  hand, 
the  syntax  is  kept  short  (the  first  letter  suffices  to  name  the 
key  words).  They  are  ALL,  BACKGROUND, 
COMMANDS,  ERRORS,  INTERMEDIATES,  LABELS, 
NORMAL,  RESULTS,  SCAN  and  OFF.  If  the  result  of  the 
expression  you  enter  does  not  display  one  of  these  sub-key 
words,  the  interpreter  attempts  to  convert  it  into  an  integer 
value.  If  this  is  not  possible,  an  error  message  occurs. 

Two  special  characters  precede  the  key  words:  "?"  controls 
interactive  tracing  and  "!"  toggles  execution  of  external 
commands. 

Positive  numeric  entry  forces  a  certain  number  of  lines  in 
the  TRACE  to  elapse  before  the  next  display.  Negative 
values  indicate  the  number  of  lines  to  be  skipped  by  the 
trace  function.  Negative  values  are  only  considered  during 
interactive  tracing. 
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See  also:       TRACE() 
1  UPPER 


Syntax:         upper  vsymbol   [vsymbol   . . . ] 

Function:  The  content  of  the  variables  following  UPPER  are 
converted  to  capital  letters.  If  a  stem  is  specified,  all 
variables  with  this  stem  are  affected.  Entering  an  undefined 
variable  is  not  an  error,  instead  it  leads  (if  active)  to  a 
NOVALUE  interrupt.  Although  you  can  use  the  built-in 
functions  TRANSLATE()  or  UPPER(),  the  UPPER 
instruction  is  faster  and  easier,  especially  if  several  variables 
are  to  be  converted. 

See  also:       TRANSLATEQ,  UPPERQ 
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6.4     Commands 


The  special  quality  of  the  Rexx  language  is  that  there  is  an  entire  class  of 
syntactic  units  that  are  not  evaluated  by  the  interpreter.  Instead,  they  are 
passed  to  an  external  environment.  Each  clause  that  contains  an 
expression  unknown  to  the  interpreter  is  seen  as  a  command  meant  for 
an  external  environment  and  passed  on.  These  instructions  are  directed 
with  ADDRESS.  You  can  send  a  DOS  (COMMAND)  or  an  application 
program  call  using  the  ARexx  interface.  The  expression  is  analyzed  and 
passed  on  to  the  external  environment  as  a  character  string.  Then  the 
external  program  executes  your  entry  and  passes  back  a  return  code  that 
indicates  whether  or  not  the  execution  was  successful. 

The  result  can  also  be  a  character  string.  The  advantage  to  this 
characteristic  is  that  macro  programs  can  easily  be  created  to  control  and 
expand  application  programs.  As  indicated,  a  command  is  any  expression 
that  has  no  meaning  for  the  interpreter.  The  command  structure  you  type 
is  entirely  dependent  on  the  external  program  for  which  it  is  intended. 
Often  that  is  an  alphanumeric  name,  followed  by  parameters.  Commands 
can  be  written  as  strings  or  symbols.  If  you  do  not  intend  to  pass  the 
name  as  a  variable  parameter,  it  is  safer  to  enter  it  as  a  literal  (string),  since 
then  it  will  not  be  mistakenly  read  as  an  ARexx  key  word  or  redefined  in 
a  variable  assignment.  For  example: 


jumpto  L+3  C 

"select  disk  font"  "ruby. font"  12 

"end  of  file" 


are  all  valid  commands  for  "CygnusEd  Professional  2".  They  can  be 
executed  by  CygnusEd  if  "ADDRESS  rexx_ced"  indicates  that  the 
CygnusEd  ARexx  port  is  the  target  for  the  commands. 
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7.    ARexx  Functions 


The  basic  idea  of  function  definition  is  to  indicate  a  program  or  a  group 
of  directions  should  always  be  carried  out  when  the  function  name 
appears  in  an  expression.  In  ARexx,  a  function  can  be  part  of  a  program 
(internal  function),  a  built-in  interpreter  function,  in  an  external  function 
library,  or  a  stand-alone  program.  The  interpreter  recognizes  function 
calls  when  a  symbol  or  string  is  followed  directly  by  a  left  open 
parenthesis  "(".  The  symbol  or  string  indicates  the  function  name  and  a 
list  of  arguments  begins  after  the  open  parenthesis.  There  can  be  several 
expressions  (that  can  contain  functions)  separated  by  commas  to  form 
arguments  or  none  at  all.  The  expression  is  analyzed  from  left  to  right  and 
passed  to  the  function.  The  following  are  valid  function  calls: 


DIGITS ( ) 

"XRANGETA",  »Z") 
showdir  (  °dhO  :  fonts  ■ 


There  is  no  limitation  on  the  number  of  arguments  passed  to  internal 
functions;  the  maximum  arguments  that  can  be  passed  to  external 
functions  is  15.  The  result  is  a  string  that's  used  in  place  of  the  function 
call.  Functions  are  also  retrieved  with  CALL  (see  Chapter  6).  Use  CALL 
when  no  result  string  is  needed. 

During  a  function  ARexx  searches  for  the  function  in  a  specific  function 
order: 

1.  Internally:  If  the  function  name  appears  as  a  label  in  the  script,  the 
current  state  of  interpretation  is  secured  (including  status 
information  such  as  TRACE  and  NUMERIC  settings).  At  the 
location  where  the  function  is  found,  execution  continues.  When  it 
ends,  with  a  RETURN  clause,  there  must  be  a  final  argument.  In 
other  words,  a  function  must  return  a  value.  If  the  function  name 
was  specified  as  a  string,  this  step  of  the  search  is  omitted. 

2.  Built-in:  The  built-in  function  library  is  searched  for  the  given 
function.  All  names  in  the  library  are  spelled  with  capital  letters; 
they  are  described  in  the  following  sub-sections  of  this  book. 

3.  External  function  libraries  and  environments:  All  available  function 
libraries  are  stored  in  a  list  that  simultaneously  sets  priorities  for  the 
search  order.  Each  function  library  is  searched  with  a  separate  offset 
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"QUERY"  to  check  whether  or  not  the  given  name  is  in  the  library. 
External  function  environments  are  called  using  a  message  protocol 
similar  to  a  command  syntax. 

4.  External  ARexx  programs:  Finally,  the  interpreter  tries  to  start  an 
ARexx  program  with  this  name.  The  current  directory  is  searched 
first,  then  the  logical  device  "REXX:".  Upper  or  lowercase  spelling 
do  not  matter. 

Internal  and  built-in  functions  do  apply  capitalization.  For  external 
functions  it  depends  on  the  comparison  algorithm  being  used  in  the 
QUERY  routine.  If  you  must  use  lowercase  letters  in  a  function  name,  the 
call  to  the  function  must  be  a  written  as  a  string,  since  symbols  are  always 
converted  to  uppercase  and  the  lowercase  distinctions  are  lost. 

7.1      ARexx  Internal  Functions 

During  a  call  to  an  internal  function,  the  interpreter  creates  a  new  storage 
environment  for  various  internal  status  data.  The  following  settings  are 
saved: 

the  NUMERIC  setting 

the  TRACE  setting 

the  SIGNAL  setting 

the  current  and  previous  environment  address 

the  current  prompt  string,  defined  with  the  OPTIONS  prompt 

Although  all  previous  variables  remain  accessible,  this  can  be  set  to  your 
needs  with  a  procedure  call.  If  a  RETURN  appears  during  the  execution 
of  the  function,  the  function  ends,  all  changes  are  discarded  and  the  old 
settings  are  restored. 


7.2     Built-in  Functions 


ARexx  contains  a  sizable  library  of  functions  that  contribute  to  the 
scope  of  the  language.  They  have  been  optimized  and  should  be 
preferred  in  most  situations,  over  an  interpreted  function. 
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7.3     ARexx  External  Function  Libraries 

External  function  libraries  can  be  used  to  expand  the  scope  of  the 
ARexx  language.  A  function  library  contains  one  or  several  functions 
and  a  special  "QUERY"  access  point  with  which  you  determine  whether 
the  function  is  in  a  library.  Libraries  have  the  same  structure  as  normal 
Amiga  libraries  (with  the  exception  of  their  significance  for  ARexx). 
Before  an  external  function  can  be  used,  the  corresponding  library  must 
be  placed  in  the  list  of  available  function  libraries  in  the  Rexx  master 
process,  with  the  built-in  function  ADDLIB(...). 

You  can  also  set  a  search  priority  order  in  the  function  call;  if  priority 
ratings  are  equal,  the  order  of  mention  determines  the  search  order. 
During  a  search  procedure,  the  Rexx  master  procedure  opens  and  loads 
each  listed  library,  unless  the  library  has  already  been  called.  The  query 
function  is  called  with  the  desired  function  names  as  arguments. 
Normally,  the  entry  point  for  this  function  is  offset  -30;  other  values  can 
be  set  with  ADDLIB(.„).  (CAUTION:  false  values  here  lead  to  a  system 
crash.)  If  the  function  is  not  found,  an  error  code  is  returned,  the  library  is 
closed  and  the  next  library  is  searched.  The  offset  of  the  function  is 
returned  if  the  search  is  successful.  Then  the  function  is  accessed  by  the 
interpreter  with  the  given  arguments.  It  must  return  an  error  code  (if 
successful,  this  is  0)  and  a  result  string. 

The  "rexxsupportlibrary"  is  included  in  ARexx  and  offers  several 
Amiga-specific  functions.  There  are  also  several  Public  Domain  libraries, 
such  as  a  math  library,  that  makes  more  functions  available. 

External  function  environments  are  accessed  by  directing  a  function 
message  to  the  appropriate  Public  Message  Port.  The  program  can  do 
whatever  is  internally  necessary  with  the  function  call;  it  must  only 
answer  the  message  at  some  time,  sending  back  a  return  code  and  a  result 
string. 

The  resident  ARexx  process  itself  is  an  example  of  a  function 
environment;  it's  always  available  via  its  message  port  "REXX",  to  which 
program  calls  can  be  sent.  It's  located  in  the  library  list  of  the  Rexx  master 
tasks  and  it  takes  a  priority  of  -60.  If  it  receives  a  function  call,  it  looks  for 
a  file  with  the  appropriate  name,  the  search  path  is  the  same  as  for  Rexx 
sub-programs:  the  current  directory,  then  the  REXX:  device.  Each 
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directory  is  searched  first  with  the  current  extension  (see  PARSE 
SOURCE)  and  following  that  without  the  extension.  By  explicitly 
entering  the  search  path  within  the  function  name,  this  process  can  be 
avoided.  External  programs  are  always  started  as  separate  processes.  The 
calling  program  waits  until  its  message  is  answered. 

Built-in  functions  are  internally  set  to  DIGITS()=9  and  FUZZ()=0  and  are 
usually  not  influenced  by  settings  in  effect  within  the  calling  program. 
Lengths  must  be  entered  as  positive  integers  (including  0)  and  positions 
cannot  be  0. 

Many  functions  process  both  necessary  and  optional  arguments. 
Optional  arguments  are  printed  in  square  parentheses  in  the  syntax 
descriptions  following.  If  you  leave  these  arguments  out,  a  default  setting 
is  usually  assumed. 

If  a  function  option  can  be  selected  with  a  single  key  word,  usually  the 
first  letter  will  suffice.  (Upper  or  lowercase  characters  don't  matter.)  If  an 
empty  string  appears  in  that  place,  a  default  setting  is  used. 

Some  functions  create  and  manipulate  external  DOS  files.  These  files  are 
called  with  a  logical  filename  that  was  determined  when  the  file  was 
opened.  This  name  is  sensitive  to  upper  and  lowercase  spelling.  An 
unlimited  number  of  files  can  be  open  simultaneously.  Luckily,  they  don't 
all  have  to  be  individually  closed;  the  interpreter  handles  the 
"housekeeping"  at  the  end  of  each  program. 

I/O  functions  String  functions 

CLOSE  ()  ABBREVO 

EOF ( )  CENTER ( ) 

EXISTS ( )  CENTRE ( ) 

LINES ( )  COMPRESS ( ) 

OPEN ( )  COMPARE ( ) 

READCH ( )  COPIES ( ) 

READLN ( )  DATATYPE ( ) 

SEEK ( )  DELSTR ( ) 

WRITECH ( )  DELWORD ( ) 

WRITELN ( )  FIND ( ) 

INDEX ( ) 

INSERT ( ) 

LASTPOS ( ) 
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LEFT ( ) 
LENGTH ( ) 
OVERLAY ( ) 
POSO 
REVERSE ( ) 
RIGHT  ( ) 
SPACE ( ) 
STRIP ( ) 
SUBSTR ( ) 
SUBWORD ( ) 
TRANSLATE ( ) 
TRIM  ( ) 
UPPER ( ) 
VERIFY ( ) 
WORD ( ) 
WORDINDEX ( ) 
WORDLENGTH ( ) 
WORDS ( ) 
XRANGE ( ) 

Bit  manipulation 

BITAND ( ) 
BITCHG ( ) 
BITCLR ( ) 
BITCOMP ( ) 
BITOR ( ) 
BITSET ( ) 
BITTST  ( ) 
BITXOR ( ) 

Numeric  functions 

ABSO 
DIGITS  ( ) 
FORMO 
FUZZ ( ) 
MAXO 
MINO 
RANDOM () 
RANDUO 
SIGNO 


TRUNC ( ) 

Conversions 

B2CO 
C2BO 
C2D() 
C2XO 
D2CO 
D2X() 
X2CO 
X2D() 

System  functions 

ADDLIB ( ) 
ADDRESS ( ) 
ARGO 
DATE ( ) 
ERRORTEXT ( ) 
EXPORT ( ) 
FREESPACE ( ) 
GETCLIP ( ) 
GETSPACE ( ) 
HASHO 
IMPORT ( ) 
PRAGMA ( ) 
REMLIB ( ) 
SETCLIP ( ) 
SHOW ( ) 

SOURCELINE ( ) 
STORAGE ( ) 
SYMBOL ( ) 
TIME ( ) 
TRACE ( ) 
VALUE () 
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7.4     I/O  Functions 


ICLOSEQ 


Syntax: 


CLOSE (name) 

Closes  the  file  with  the  given  logical  filename.  The  function 
returns  1  if  the  file  close  was  successful;  otherwise  (if  the 
file  was  not  open)  a  0  is  returned. 


See  also: 
Example: 
IEOFQ 


OPENO 

SAY  CLOSE ( "Datadump " ) 


==>  1 


Syntax:         EOF  (name) 

Returns  a  1  if  the  end  of  the  given  logical  file  has  been 
reached;  otherwise  a  0  is  returned. 

Example:       if  EOF ("Datadump")    then  CLOSE (" Datadump " ) 


IEXISTSQ 


Syntax:         EXISTS  (DOSf  ilename) 

Determines  if  a  file  with  the  given  name  exists.  If  successful, 
the  function  returns  a  1;  otherwise  a  0  is  returned.  Path 
names  can  precede  the  filename. 

Example:       if  EXISTS ("dhO:Trashcan/LoadWB")  then  say, 

"Look  at  the  new  Workbench  1.3,  before  you 
empty  the  trash . " 


ILINESQ 


Syntax:         LINES  (  [name] ) 


] 


Returns  the  number  of  lines  listed  in  the  entry  buffer  of  the 
logical  file  "name"  that  mast  belong  to  an  interactive  device 
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like  CON:  or  SER:.  If  "name"  is  omitted,  the  number  of  lines 
"stdin"  is  returned. 


Example:       say  LINES  ("Pipeline") 
say  LINES  0 


==>  3    (for  example) 
==>  1    (for  example) 


IQPENQ 


Syntax:  OPEN(name, DOS-f ilename [ , "Append" I "Read" I "Write" ] ) 

Opens  a  file  for  the  given  operation  and  gives  it  a  logical 
filename  ("name")  that  can  later  be  called.  "DOSfilename"  is 
the  name  of  the  file  to  be  opened  and  this  can  include 
device  and  directory  names. 

APPEND  Opens  an  existing  file  and  sets  the  current 

position  to  the  end  of  the  file  in  order  to  add 
data. 


See  also: 
Example: 


READ  Opens  an  existing  file  and  sets  the  current 

position  to  the  beginning  of  the  file. 

WRITE  Opens  a  new  file;  if  a  file  of  the  same  name 

exists,  it  is  erased. 

To  call  these  keywords,  simply  type  the  first  letter.  If 
nothing  is  entered,  READ  is  assumed  to  be  the  function 
you  are  calling.  When  calling  devices  that  do  not  support  a 
"seek"  function,  such  as  CON:  or  SER:,  the  method  of  file 
access  does  not  matter.  The  result  of  the  function  is 
Boolean.  An  unlimited  number  of  files  can  be  open 
simultaneously  and  they  are  all  automatically  closed  when 
you  leave  the  program. 

CLOSEO,  READxx(),  WRITExx(),  SEEK() 

Success  =  OPENCDatastack"  ,  "RAM:T/Testdata"  ,  "W") 

Success  =  OPEN ("Window", "CON:200/100/200/100/RexxConsole") 
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IREADCHQ 


Syntax: 


READCH (name , number) 


Reads  the  "number"  of  characters  in  the  open  logical  file 
"name".  This  function  returns  the  characters  it  reads  as  the 
result  string,  or  fewer  than  requested  if  the  end  of  file  is 
reached.  If  you  are  reading  from  an  interactive  device  like 
CON:  or  SER:,  the  function  does  not  return  anything  until 
the  necessary  number  of  characters  are  in  the  buffer; 
execution  halts  until  then.  Reading  from  non-interactive 
devices  is  useless  and  leads  to  a  false  result. 

Example:       data  =  READCH("Dataheap", 5) 


IREADLNQ 


Syntax:         READLN  ( Name ) 


See  also: 
Example: 


ISEEKQ 


Reads  characters  from  the  logical  file  "name"  until  a  line 
feed  (Hex  OA)  or  the  end  of  the  file  is  encountered.  The  line 
feed  itself  is  removed  and  the  entire  line  is  returned  as  the 
result.  If  you  are  reading  an  interactive  device  like  CON:  or 
SER:  the  function  does  not  return  until  a  complete  line  is  in 
the  buffer;  execution  halts  until  then. 

READCHO 

Entryline  =  READLN ( "Window") 


] 


Syntax:  SEEK(name,    offset [ , "Begin" I "Current" I "End" ] ) 

Sets  the  current  position  for  calls  to  the  open  logical  file 
"name".  "Offset"  determines  the  distance  in  characters  from 
the  current  position.  Whole  numbers  (including  negative 
numbers)  are  allowed.  By  entering  the  keyword  "Begin" 
the  "offset"  is  set  to  the  file  beginning;  "End"  sets  it  to  file 
end.  You  can  overstep  the  limits  of  the  file,  but  this  is  not 
recommended,  since  it  can  lead  to  some  confusion  and 
sometimes  to  errors.  The  result  of  SEEK  is  the  current 
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position  in  reference  to  the  beginning  of  the  open  file. 
Using  SEEK  with  interactive  devices  is  senseless  and  has 
no  effect. 

Example:       say  SEEK("Datahaystack",5,  "B")    ==>  5 
filelength  =  SEEK ("Datahay stack" , 0, "E") 

IWRITECHQ  ~l 

Syntax:         WRITECH  (name,  string) 

Writes  "string"  to  the  logical  file  "name"  and  returns  the 
number  of  characters  written. 


Example:       say  WRITECH ( "Datahaystack" , "needle" ) 


==>   6 


IWRITELNQ" 


Syntax:         WRITELN  (name ,  string) 

Writes  "string"  to  the  logical  file  "name"  and  adds  a  line 
feed  (Hex  0A).  Returns  the  number  of  characters  written, 
including  the  added  line  feed. 


Example: 


say  WRITELN ( "Window" , "The  rose   is   red.") 


=>  17 
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7,5     ARexx  String  Functions 


IABBREVQ 


Syntax:         ABBREV  ( stringl ,  string2  [ ,  length]  ) 

Returns  a  1  if  "string2"  is  a  permitted  shorthand  of  "stringl" 
and  is  not  shorter  than  "length".  The  default  for  "length"  is 
the  length  of  "string2".  An  empty  character  string  is  a  valid 
shorthand  if  nothing  is  specified  in  "length". 

Example:  say  ABBREVC'Rosegarden",  "Rose")  ==>  1 
say  ABBREV ( "Rosegarden" , "R" , 4 )  ==>  0 
say  ABBREVC'Rosegarden","")  ==>  1 


ICENTERQ  or  CENTREQ" 


Syntax: 
or: 


CENTER (string, length [, pad] ) 
CENTRE (string, length [, pad] ) 

Returns  a  character  string  of  given  length,  in  which  the 
"string"  is  centered.  Empty  spaces  to  the  left  and  right  are 
replaced  with  spaces  or  pad  (one  character).  If  the  "string" 
is  too  long,  each  side  is  cut.  To  avoid  errors,  both  American 
and  English  spelling  is  permitted. 


Example: 


say  CENTERf "Hello", 10) 
say  CENTRE("0123456789",5) 
say  CENTER ("TEST ",10,  ">") 


=>  '    Hello 

=>  '23456' 

=>  '  »>TEST>» ' 


ICOMPRESSCT 


Syntax: 


Example: 


COMPRESS ( string [, list] ) 

If  the  second  argument  is  omitted,  this  function  removes  all 
empty  space  from  "string".  In  "list"  one  or  several  characters 
can  be  specified  that  are  then  removed  instead  of  the 
spaces. 

say  COMPRESS  (  "  Hey  you !  " )  ==>  ■  Heyyou !  ' 

say  COMPRESS ("##AM++I#G+A++", •#+")    ==>  'AMIGA' 
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ICOMPAREQ" 


Syntax:         COMPARE  ( stringl ,  string2  [ ,  pad]  ) 

Returns  the  position  of  the  first  character  of  the  two  strings 
found  not  to  be  equivalent.  If  they  agree,  the  result  is  0.  If 
necessary,  a  shorter  string  is  filled  with  empty  space  to  the 
right  or  an  end  of  file  marker,  if  that's  found  in  the  other 
string. 

Example:       say  compare ("Rose", "Ross")  ==>  4 

say  COMPARE ( "abc" , "abc+-", "+")         ==>  5 


ICOPIESQ 


Syntax:         COPIES  (string, number) 

Returns  the  "number"  of  repetitions  of  the  "string" 
"Number"  must  be  a  whole  number  or  zero. 


Example:       say  copies  ( "  Rose " ,  3 ) 
say  COPIES (" Rose ",0) 


=> 
=> 


' RoseRoseRose1 


IDATATYPEQ" 


Syntax:         DATATYPE  ( string  [ ,  type ]  ) 

If  only  one  parameter  is  specified,  the  function  tests 
whether  the  argument  is  a  valid  ARexx  number  and  returns 
"NUM".  Otherwise,  the  result  is  "CHAR".  If  one  of  the 
following  keywords  is  entered  for  "type",  a  test  is  executed 
and  1  is  returned  if  "string"  is  that  type;  otherwise  a  0  is 
returned.  A  null  string  only  returns  a  1  when  tested  for 
hexadecimal  (X). 
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Available  key  words  are: 


Alphanumeric 

A-Z,  a-z  and  0-9 

Binary 

valid  binary  string 

Lowercase 

a-z 

Mixed 

A-Z  and  a-z 

Numeric 

valid  ARexx  numbers 

Symbol 

valid  ARexx  symbols 

Upper 

A-Z 

Whole 

whole  numbers 

X 

valid  hexadecimal  string 

Example :      s  ay  datatype  ("4711")  = = >  num 

say   DATATYPE ( "Rose ", "L")  ==>    0 

say  DATATYPEC52    6F   73    69"x,"X")        ==>   1 

IDELSTRQ  | 

Syntax:         DELSTR  ( string,  n  [ ,  length]  ) 

Returns  the  "string",  after  "length"  characters  from  position 
"n"  have  been  removed.  If  "length"  is  omitted,  the  rest  of 
the  character  string  is  removed. 


Example: 


say  DELSTR ("The  Rose  is  red", 5, 5)    ==>  The  is  red 


IDELWORDQ" 


H 


Syntax:  DELWORD( string,  n[ ,  length]  ) 

Returns  the  "string",  after  "length"  words  have  been 
removed  from  and  including  word  number  "n".  If  "length"  is 
omitted,  the  rest  of  the  string  is  removed.  Empty  space  in 
front  of  the  first  word  that  is  not  deleted  remains. 


Example: 


say  DELWORD("The  Rose  is  red, 3,1)    ==>  The  Rose  red 


526 


7.5  ARexx  String  Functions 


IFINDQ 


Syntax:         FIND  (string,  words) 

Searches  for  "words"  in  "string"  and  returns  the  word 
number  of  the  first  such  agreement  within  "string".  If 
"words"  is  not  in  "string",  the  function  returns  a  0. 


Example: 
IINDEXQ 


say  FINDC'The  Rose  is  red",  "Rose  is") 


==>  2 


Syntax:  INDEX  (string, pattern  [,  start]  ) 

Searches  for  the  first  appearance  of  "pattern"  in  "string" 
from  the  beginning  of  the  string  or  from  the  optional 
position  "start".  The  function  returns  either  the  position 
number  or  0,  if  "pattern"  does  not  appear. 


Example: 

Caution: 
See  also: 
IINSERTQ 


say   INDEXC'The  Rose   is   a  Rose" , "Rose" )  ==>   5 

say   INDEX("The  Rose   is   a  Rose" , "Rose" , 10)  ==>   15 

say   INDEXC'The  Rose   is  a  Rose" , "Carnation" )  ==>  0 

This  function  is  unique  to  ARexx  and  does  not  follow  the 
typical  order  of  arguments  in  Rexx  syntax. 

LASTPOS()  is  similar  to  POS(),  except  it  has  reversed 
arguments. 


Syntax:  INSERT ( sour ce.dest in [, [start] [, [length] [,pad] ] ] ) 

Adds  "source"  after  the  "start"  position  to  the  "destin" 
string.  "Source"  is  expanded  with  the  character  "pad"  to 
the  given  "length".  The  default  value  for  "start"  is  0,  for 
"length"  the  length  of  the  "source",  and  the  "pad"  default  is 
a  space. 

Example:        say   INSERT("123","abcde")  ==>   123abcde 

say   INSERT("123", "abcde",6,5, ".")  ==>  abode . 123 . . 
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ILASTPOSQ" 


Syntax:         LASTPOS  (pattern,  string [,  start]  ) 

Searches  "string"  backward  for  the  first  appearance  of 
"pattern"  and  returns  the  equivalent  index  (or  0,  if  no 
agreement  occurs).  Normally,  the  search  begins  at  the  last 
character.  If  you  want  the  process  to  start  somewhere  else, 
"start"  indicates  a  position  counted  from  the  beginning. 

Example:        say  LASTPOS (" Rose",  "The  Rose  is  a  Rose")       ==>  15 
say  LASTPOS ( "Rose" , "The  Rose  is  a  Rose", 15)    ==>  5 
say  LASTPOS ( "Carnation" , "The  Rose  is  a  Rose")  ==>  0 


ILEFTQ 


Syntax:         LEFT  (string,  length [  ,pad]  ) 

Returns  a  character  string  of  the  indicated  "length",  taken 
from  the  left  side  of  the  argument  "string".  If  necessary, 
"string"  is  cut  off  at  the  right  end  or  lengthened  with  "pad". 
Default  for  "pad"  is  a  space  character. 


Example:       say  LEFT ("The  Rose  is  red",  8) 
say  LEFT ("The  Rose" , 10, " : " ) 


==>  The  Rose 
==>  The  Rose: : 


ILENGTHQ 


Syntax:         LENGTH  ( s t r ing ) 

Returns  the  length  of  "string". 

Example:       say  length ("The  Rose") 
say  LENGTHC") 


==>    8 
==>    0 


IQVERLAYQ" 


Syntax:         overlay (new, old [ , [ start ] t , [ length] [ , pad] ] ] ) 

Overlays  the  character  string  "old"  with  "new",  beginning 
at  the  position  "start".  During  the  operation,  "new"  is  cut  to 
"length"  or  lengthened  with  the  "pad"  character.  The 
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default  value  of  "start"  is  1,  if  the  value  is  greater  than  the 
length  of  "old",  the  extra  space  is  filled  with  "pad".  The 
default  setting  for  "length"  is  the  length  of  "new".  The 
standard  pad  character  is  a  space. 


Example: 


say  OVERLAY ("xx", "The  Rose") 

say  OVERLAY ("Rose", "The", 7, 6, "*") 


==>  xxe  Rose 

==>  The***Rose** 


fPOSQ" 


Syntax:  POS  (pattern,  string! ,  start]  ) 

Searches  for  the  first  appearance  of  "pattern"  in  "string" 
from  the  optional  position  "start".  If  no  "start"  is  specified,  it 
searches  from  the  beginning  of  the  file.  It  returns  either  the 
position  at  which  the  pattern  is  found  or  0,  if  "pattern"  does 
not  occur  at  all. 

Example:         say  POS(" Rose", "The  Rose  is  a  Rose")         ==>  5 
say  POS ( "Rose" , "The  Rose  is  a  Rose", 10)       ==>  15 
say  POS ( "Carnation", "The  Rose  is  a  Rose")     ==>  0 


IREVERSEQ" 


Syntax:         REVERSE  ( string) 

Reverses  the  order  of  characters  in  "string". 
Example:       say  reverse  ( "esoR" )  ==>  Rose 

|  RIGHTQ  I 

Syntax:         RIGHT  (string,  length [  ,pad]  ) 

Returns  a  character  string  of  "length"  containing  "string", 
starting  from  the  right.  "String"  is  cut  off  at  the  left  side  if 
necessary,  or  lengthened  with  the  "pad"  character.  The 
default  character  for  "pad"  is  a  space. 

Example:       say  RIGHT ("The  Rose  is  red", 3)   ==>  red 

say  RIGHT("The  Rose" ,10, " : ")        ==>    : :The  Rose 
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ISPACEQ 


Syntax:         SPACE  ( string, n  [  ,pad]  ) 

If  "string"  contains  words  separated  by  spaces,  SPACE 
returns  a  character  string  with  "n"  spaces  between  the 
words.  Empty  spaces  on  the  left  and  right  are  removed.  The 
"pad"  character  can  define  another  character  to  use  instead 
of  the  space  character. 


Example:  say  SPACE ("The   Rose  is  red",l) 

say  SPACE!"   The  Rose  is  red", 2) 
say  SPACE("  The  Rose  is   red", 1, " I ■) 


==>  The  Rose  is  red 
==>  The  Rose   is   red 
==>  The  I  Rose  I  is  I  red 


Caution:  This  function  does  not  work  correctly  if  the  second 
argument  is  omitted.  The  default  value  for  "n"  is  0  (it  should 
be  1).  Omitting  the  second  argument  of  this  feature  has  not 
been  documented;  it  cannot  be  recommended.  Eventually 
this  error  will  be  corrected. 


ISTRIPQ 


] 


Syntax:  STRIP (string [ , [{"B" I "L" I "T"}] [.character] ] ) 

If  an  argument  is  given,  the  function  removes  preceding 
and  trailing  spaces  from  "string".  If  "L"  (for  "leading")  or  "T" 
(for  trailing)  is  indicated,  only  one  or  the  other  is  removed. 
The  third  argument  is  used  to  specify  the  character  to  be 
removed. 

Example:         say  STRIP ("  The  Rose  ")  ==>  'The  Rose' 

say  STRIP ("  The  Rose  ",*T")        ==>  '  The  Rose' 
say  STRIP("--The-Rose--",,  "--)     ==>  'The-Rose' 


ISUBSTRQ 


3 


Syntax:         SUBSTR  (string,  start  [,  [length]  [  ,pad]     ]) 

Returns  a  sub-string  of  "string",  from  the  position  "start",  for 
"length"  and  filled  at  the  right  side  with  the  character 
"pad".  Default  for  "length"  is  the  remaining  length  of 
"string",  the  default  pad  character  is  a  space. 
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Example:       say  SUBSTR  ( "  abcde " ,  3 )        ==>  cde 
say  SUBSTR ("123 45", 3, 2)       ==>  34 
say  SUBSTR ( "abcde", 3, 5, "#")   ==>  cde## 


ISUBWORDpT 


Syntax:  SUBWORD  ( string,  start  [ ,  length]  ) 

Returns  a  sub-string  of  "string",  starting  with  the  word  at 
"start"  and  containing  the  number  of  words  set  in  "length". 
The  default  setting  is  the  remainder  of  "string".  The  result 
contains  no  leading  or  trailing  spaces,  only  the  space 
between  the  selected  words  is  preserved. 

Example:       say  SUBWORD("The  Rose  is  red",  3)       =>  is  red 
say  SUBWORD ("The  Rose  is  red", 2, 2)  =>  Rose  is 


ITRANSLATEQ" 


Syntax: 


TRANSLATE (string [, [output] [, [input] [,pad]]]) 

Replaces  the  characters  in  one  string  with  the  characters  in 
the  other  and  returns  the  new  character  string. 
TRANSLATEO  has  the  same  effect  as  UPPER()  with  a 
single  argument.  Default  for  "input"  is  a  string  with  all 
characters  from  "00"x  to  "FF'x.  Every  character  that  occurs 
in  "input"  is  replaced  with  the  corresponding  character  in 
"output".  If  there  is  no  such  character  in  "output"  (if 
"output"  is  shorter  than  "input"),  an  empty  space  or  the 
"pad"  character  is  returned.  Characters  that  do  not  occur  in 
"input"  remain  the  same;  the  length  of  the  "string"  does  not 
change.  The  tables  can  be  as  long  as  you  want,  but  longer 
than  256  characters  hardly  makes  sense,  since  within 
"input"  only  the  first  appearance  of  a  character  is  noted. 
The  final  example  shows  the  use  of  TRANSLATEO  to 
rearrange  a  character  string  in  any  order.  "String" 
determines  the  order  and  the  second  argument  gives  the 
specific  working  character  string. 


Example: 


say  TRANSLATE ("The  Rose") 

say  TRANSLATE ( "xyz " , " wvu " " , " zyx" ) 

say  TRANSLATE ("12345", "ab», "123", "-") 


==>  THE  ROSE 
==>  uvw 
==>  ab-45 
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say  TRANSLATE ("312°, "abc", "123") 


==>  cab 


ITRIMQ 


Syntax: 


Example: 
IUPPERQ 


TRIM (string) 

Removes  trailing  spaces  from  "string".  Equivalent  to  the 
STRIP(string,"T")  function. 


say  TRIM("   Rose    ") 


Rose' 


Syntax:         UPPER  (string) 


Converts  "string"  to  capital  letters.  Equivalent  to  the 
TRANSLATE(string)  function  but  a  little  bit  faster  with 
short  character  strings. 


Example:       say  UPPER  ( "  Rose " ) 


==>   ROSE 


IVERIFYQ 


Syntax:         VERIFY  (string,  table  [ ,  [{MIN}]  [,  start]  ]  ) 

Checks  if  "string"  only  contains  characters  in  "table".  If  so  a 
0  is  returned;  otherwise  the  position  of  the  first  character 
that  does  not  appear  in  "table"  is  returned.  The  third 
argument  can  be  "match"  (default  is  "nomatch")  to  reverse 
the  logic  of  the  verification.  The  VERIFY()  function  in 
"match"  mode  returns  the  position  of  the  first  character  that 
is  contained  in  "table".  Normally  the  search  begins  at  the 
first  character,  but  "start"  can  be  used  to  define  another 
entry  point.  If  "string"  is  empty,  or  "start"  is  greater  than  the 
length  of  "string",  the  function  always  returns  0,  regardless 
of  the  third  argument. 

Example:       say  VERIFY( "427" , "0123456789")  ==>  0 

say  VERIFY ("4p7ql", "0123456789")  ==>  2 

say  VERIFY ("xx7 31", "0123456789", "M")  ==>  3 

say  VERIFY ("4p7ql", "0123456789", ,3)  ==>  4 
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IWORDQ 


Syntax:         WORD  ( s  t  r  ing ,  n ) 

Returns  the  "n"-th  word  in  "string",  or  an  empty  string  if 
"string"  does  not  contain  sufficient  words.  Equivalent  to 
the  SUBWORD(string,n,l)  function. 

Example:       say  WORD ("The  Rose  is  red", 2)        ==>  Rose 

IWORDINDEXQ  ~| 


Syntax:         WORDINDEX(  string,  n) 

Returns  the  position  of  the  first  character  of  the  "n"-th 
word  in  the  "string",  or  0  if  there  are  insufficient  words. 

Example:       say  WORDlNDEXC'The  Rose  is  red", 2)  ==>  5 

IWORDLENGTHQ  1 


Syntax:         WORDLENGTH(  string,  n) 

Returns  the  length  of  the  "n"-th  word  in  "string",  or  0  if 
there  are  insufficient  words  in  "string". 

Example:       say  WORDLENGTHC'The  Rose  is  red", 2)         ==>  4 

IWORDSQ  | 


Syntax:         WORDS  (string) 

Returns  the  number  of  words  in  "string". 
Example:       say  WORDS ("The  Rose  is  red")  ==>  4 

IXRANGEQ  1 

Syntax:         XRANGE  (  [start ]  [ ,  end]  ) 

Returns  a  character  string  containing  all  characters  with 
ASCII  codes  ranging  from  the  "start"  to  the  "end" 
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character.  Default  for  "start"  is  "00"x  and  for  "end"  it  is 
"FF'x.  The  order  is  always  from  high  to  low;  if  "start"  is 
higher  than  "end",  the  order  begins  again  after  "FF'x  at 
"00"x  and  continues  until  the  "end"  value. 

Example:       say  c2x(xrange() )      ==>  000102  ...  fdfeff 

say   XRANGEC'A",  "F" )  ==>   ABCDEF 

say  C2X(XRANGE(, "05"x)  )   ==>   000102030405 
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7.6      Bit  Manipulation  in  ARexx 

[BITANDQ 


Syntax: 


BITAND ( stringl [ , [ string2 ] [ , pad] ] ) 


A  logical  AND  function  is  performed  with  the  two  strings. 
The  result  has  the  length  of  the  longer  operand.  Instead  of 
breaking  off  the  operation  at  the  end  of  the  shorter 
operand  and  appending  the  rest  of  the  longer  operand 
unchanged,  the  shorter  operand  is  filled  up  to  the  right  with 
"20"x  (the  space  character)  and  the  concatenation  AND 
performed  on  the  entire  length  of  the  string.  The  behavior 
described  in  the  documentation  can  only  be  guaranteed  if 
"pad"  is  always  specified  as  "FF'x.  The  shorter  operand  is 
then  filled  with  this  value  before  the  operation  begins.  If 
the  second  operand  is  omitted,  "20"x  is  always  filled  in  or 
the  end  of  file  marker  is  added. 


Example: 


IBITCHGQ 


say  C2B(BITAND("00001111nb, "01010101"b))==>  00000101 
say  C2x ( BITAND ("FF"x, "FFFF"x)  ==>  FF20 

say  C2x(BITAND("00"x, "AAAA"x, "FF"x)      ==>  00AA 
say  BITAND ("Rose", , "11011111"b)         ==>  ROSE 


Syntax: 


BITCHG ( string , bi t ) 


Inverts  the  given  bit  in  "string".  Bit  0  is  the  lowest  value  bit 
of  the  characters  on  the  right  side  of  "string". 


Example: 
IBITCLRQ 


say  C2B (BITCHG ("00001111"b, 5))    ==>  00101111 


Syntax: 


BITCLR ( string , bi t ) 


Deletes  the  given  bit  in  "string".  Bit  0  is  the  lowest  value  bit 
on  the  right  side  of  "string". 

Example:       say  C2B(BITCLR("00001111"b,2) )        ==>  00001101 
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IBITCOMPQ" 


Syntax:         BITCOMP(stringl,  string2  [  ,pad]  ) 

Compares  the  bit  patterns  of  the  two  strings,  from  bit 
number  0  going  from  right  to  left.  The  result  is  the  number 
of  first  bits  in  which  the  strings  are  different,  or  -1  if  they  are 
equal.  The  shorter  string  is  filled,  before  the  operation  at  the 
left  side  with  the  "pad"  character  (the  default  "pad"  is  a 
space). 

Example:       say  BlTCOMP(  "FF" ,  "FFFF"x)  ==>  8 

say   BITCOMPC'FF",  "20FF"x)  ==>    -1 


1BITORQ 


Syntax:  BITOR( string 1  [ ,  [string2]  [,pad]]) 

A  logical  OR  operation  is  performed  on  the  two  strings.  The 
result  is  the  length  of  the  longer  operand.  Instead  of 
breaking  off  the  operation  at  the  end  of  the  shorter 
operand  and  adding  the  rest  of  the  longer  operand 
unchanged,  the  shorter  operand  is  filled  with  "20"x  (the 
space  character)  and  the  OR  connection  is  carried  out  over 
the  entire  length  of  the  string.  The  behavior  that  is 
described  in  the  documentation  is  only  possible  if  the  "pad" 
is  always  specified  as  "00"x.  The  shorter  operand  is  then 
filled  up  with  this  value  before  the  logical  operation  takes 
place.  If  the  second  operand  is  omitted,  it's  filled  with  "20"x 
or  the  end  of  file  marker. 

Example:  say  C2B(BITORC,00001111"b, "OlOlOlOl-b) )  ==>    01011111 

say  C2x(BITOR("FF"x, °0000"x)  ==>   FF20 

say  C2x(BITOR("00"x, "AAAA"x, "FF"x)  ==>  AAFF 

say  BITOR("Rose°, , "00100000"b)  ==>  rose 


IBITSETQ 


Z3 


Syntax:         BITSET  (string,  bit) 

Sets  a  marker  for  the  given  bit  in  "string".  Bit  0  is  the  lowest 
value  bit  of  the  characters  from  the  right  end  of  the  "string". 
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Example:       say  C2B(BITSET("00001111"b, 5) ) 


=>   00101111 


IBITTSTQ 


Syntax:         BITTST  (string,  bit) 

Returns  the  given  bit  of  "string".  Bit  0  is  the  lowest  value 
bit  of  the  characters  from  the  right  end  of  the  "string". 


Example:       say  BITTST (" 00001111 "b, 5) 
IBITXORQ 


==>  0 


Syntax:         BlTXOR(stringl  [ ,  [string2]  [  ,pad]  ] ) 

Performs  a  logical  exclusive  OR  operation  on  the  two 
strings.  The  result  is  the  length  of  the  longer  operand. 
Instead  of  breaking  off  the  operation  at  the  end  of  the 
shorter  operand  and  adding  the  rest  of  the  longer  operand 
unchanged,  the  shorter  operand  is  filled  with  "20"x  (the 
space  character)  on  the  right  side,  and  the  XOR  operation  is 
performed  on  the  entire  length.  The  documented  behavior 
can  only  be  achieved  if  the  "pad"  is  always  "00"x.  The 
shorter  operand  is  then  filled  with  this  value  before  the 
operation  starts.  If  the  second  operand  is  omitted,  it  is 
always  filled  with  "20"x  or  the  end  of  file  marker. 

Example:         say  C2B(BITXOR("00001111"b, "01010101"b))==>  01011010 

say  C2x(BITXOR("FF°x, "0000"x)  ==>  FF20 

say  C2x(BITXOR("FF"x, "0000"x, "00"x)      ==>  FF00 

say  BITXOR("Rose", , "OOlOOOOO-b)         ==>  rOSE 
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7.7     Numeric  Functions 


[ABSQ" 


Syntax: 


Example: 


IDIGITSQ 


Syntax: 

Example: 
IFORMQ 


Syntax: 

Example: 
IFUZZQ 


Syntax: 

Example: 
IMAXQ 


ABS 

( number ) 

Returns  the  absolute  value  of 

"number". 

say 

ABS (-345) 

==>   345 

say 

ABS  (4.32) 

==>   4.32 

DIGITS  () 

Returns  the  current  NUMERIC  DIGITS  setting. 

say  DIGITS ()  ==>  9 


FORM ( ) 

Returns  the  current  NUMERIC  FORM  setting. 

say   FORMO  ==>    SCIENTIFIC 


FUZZ() 

Returns  the  current  NUMERIC  FUZZ  setting. 

say  FUZZO  ==>  0 


Syntax:         MAX  (number ,  number  [ ,  number]  .  .  .  ) 
Returns  the  largest  of  the  given  numbers. 
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Example:       say  MAX (3, 2, 7,  5) 

say  MAX(-3, -1,-8,-1) 


==>  7 
==>   -1 


IMINQ 


Syntax: 


Example: 


MIN (number, number [ , number] . . . ) 
Returns  the  smallest  of  the  given  numbers. 


say  MIN (3 ,2, 7, 5) 
say  MIN(-3, -1,-8,-1) 


==>  2 
==>   -8 


IRANDOMQ" 


Syntax:         RANDOM  (  [min]  [ ,  [max]  [ ,  [startvalue]  ]  ]  ) 

Returns  pseudo-random  integer  values  between  "min"  and 
"max".  Default  values  are  0  and  999.  The  interval  between 
"min"  and  "max"  cannot  be  larger  than  1000.  The  third 
value  can  be  a  different  start  value,  in  order  to  achieve  a 
repetitive  sequence.  This  start  value  should  be  specified  at 
the  first  call  and  can  be  any  number.  The  results  of  later 
calls  to  RANDOM()  (without  a  start  value)  are  repeated,  if 
the  random  number  generator  is  initialized  to  the  same  start 
value  again.  If  no  start  value  is  specified,  the  random 
number  generator  is  initialized  with  the  system  time  at  the 
first  call.  The  start  value  is  not  secured  for  all  routine  calls, 
but  rather  globally,  for  an  entire  program. 


Example:      say  random (1,49) 

say  RANDOM (, ,4711) 


=>  17   ? 

=>  365   ? 


| RAN DUO 


Syntax:         RANDU  (  [  startvalue  ] ) 

Returns  evenly  distributed  pseudo-random  numbers 
between  0  and  1.  The  number  of  places  after  the  decimal 
point  depends  on  the  current  NUMERIC  DIGITS  setting. 
Normally,  the  random  number  generator  is  initialized  with 
the  system  time  at  the  first  call.  By  entering  the  optional 
"start  value",  the  random  number  generator  can  be  moved 
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to  a  defined  starting  condition,  in  order  to  achieve 
repetitive  pseudo-random  sequences. 


Example: 

ISIGNQ 


say  RANDUO 


==>  0.018327461  ? 


Syntax:         S I GN  ( numbe  r ) 


Resembles  the  mathematic  "sign"  function.  If  "number"  is 
negative,  SIGN  returns  a  -1,  if  the  number  is  a  0,  it  returns  a 
0,  and  if  "number"  is  positive,  it  returns  a  1. 


Example: 


Caution: 


say  SIGN (0.1) 
say  SIGN (0.0) 
say  SIGN (-5) 


==>  1 
==>  0 
==>   -1 


ITRUNCQ 


The  SIGN()  function  should  round  the  number  according  to 
the  evaluation  of  the  NUMERIC  DIGITS  setting.  This  is  not 
implemented,  so  insignificant  fractions  are  never  reported  as 
"0". 


J 


Syntax:         TRUNC  (number  [ ,  places  ]  ) 

Returns  the  whole  number  portion  of  "number",  followed 
by  the  desired  number  of  places  after  the  decimal,  which  is 
usually  none.  It  does  not  round  to  the  whole  number.  If 
needed,  the  number  is  filled  with  zeros.  The  result  is  never 
an  exponential  notation,  so  that  "number"  cannot  require 
more  places  than  are  set  in  NUMERIC  DIGITS.  If 
necessary,  the  number  is  rounded  according  to  the  number 
of  decimal  places  first. 


Example:       say  trunc (564. 73294) 

say  TRUNC (564. 73294, 3) 
say  TRUNC (564. 7, 3) 


==>  564 

==>  564.732 
==>  564.700 
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7.8     Conversion  Functions  in  ARexx 


[B2UQ" 


Syntax:         B2C  (string) 

Converts  a  string  of  binary  symbols  (0  and  l's)  to  the 
corresponding  ASCII  character  string.  Empty  spaces  are 
allowed  in  "string"  but  only  at  the  byte  limits,  every  8th 
digit. 


Example: 
IC2BQ 


IC2DQ 


say  B2C( "01000001") 


=>   A 


Syntax:         C2B  (string) 

Converts  an  ASCII  symbol  string  to  an  equivalent  binary 
string. 

Example:         say  C2B("Rose")==>01010010011011110111001101100101 


] 


Syntax:         C2D  ( string  [  ,n]  ) 

Converts  "string"  from  a  symbolic  representation  to  the 
corresponding  decimal  number.  The  maximum  "string" 
length  is  4  bytes  (32  bits).  If  "n"  is  given,  the  binary  value 
of  "string"  is  treated  as  a  pair  of  length  "n"  bytes  and 
transformed  into  a  corresponding  whole  number  (with  a 
prefix  if  necessary).  The  "string"  is  cut  off  at  the  left  side  or 
filled  with  zeros  if  it's  not  the  right  length.  No  prefix 
evaluation  takes  place. 


Example:      say  C2D("0A"x) 
say  C2D("Rose") 
say  C2D("FFFF"x,2) 


==>   10 

==>   1383035749 

==>    -1 
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|C2X?T 


Syntax: 


C2X (string) 


Converts  "string"  from  symbolic  representation  to  the 
corresponding  hexadecimal  number.  The  result  contains 
capital  letters  for  the  numbers  A-F  and  no  empty  spaces. 


Example: 

say  C2X("Rose") 
say  C2x("0A"x) 

==>   526F7365 
==>  OA 

ID2C0 

1 

Syntax: 


D2C (numberl [ , bytes] ) 


Converts  decimal  numbers  into  equivalent  ASCII 
characters.  If  "bytes"  is  specified,  the  result  takes  that 
length;  it's  cut  off  at  the  left  side  or  filled  with  "00"x  on  the 
right  if  necessary.  Negative  values,  not  otherwise  permitted, 
can  be  expressed  as  a  pair. 


Example: 

say  D2C(65) 

say  C2X(D2C(-1,4) ) 

==>  A 

==>    FFFFFFFF 

ID2X0                                                                                                           | 

Syntax:         D2X  (numberl  [ ,  nibbles  ] ) 

Converts  whole  decimal  numbers  to  the  corresponding 
hexadecimal  notation.  If  "nibbles"  is  specified,  negative 
numbers  are  converted  into  a  number  pair.  The  result  has 
the  corresponding  number  of  places  and,  if  necessary,  is  cut 
off  at  the  left  side  or  filled  in  with  O's  at  the  right.  For  the 
numbers  A-F  it  uses  capital  letters  and  no  empty  space  is 
added. 


Example: 


say  D2X(10) 

==>  A 

say  D2X(10,2) 

==>  OA 

say  D2X(-1,5) 

==>    FFFFF 
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1X2CQ 


Syntax:         X2C(Xstring) 

Converts  a  string  from  hexadecimal  notation  to  equivalent 
ASCII  string.  If  necessary,  a  0  is  added  to  the  left,  in  order 
to  arrive  at  an  even  number  of  nibbles.  At  the  byte  limits, 
empty  spaces  can  be  added  to  improve  readability.  They 
are  ignored  by  the  program. 


Example: 
IX2DQ 


say  X2CC4D  4E") 


==>  MN 


Syntax:         X2D(Xstring[ , nibbles ]  ) 

Converts  a  string  from  hexadecimal  notation  to  the 
corresponding  decimal  number.  If  necessary,  a  single  0  is 
added  on  the  left  side,  in  order  to  arrive  at  an  even  number 
of  nibbles.  Empty  spaces  can  be  added  at  the  byte  limits  to 
improve  readability.  They  are  ignored  by  the  program.  A 
maximum  of  4  bytes  (8  nibbles)  are  allowed.  The 
NUMERIC  DIGITS  setting  has  no  influence  on  this 
function. 


Normally,  X2D()  returns  positive  numbers.  If  any  value  is 
entered  for  "nibbles",  "Xstring"  is  assumed  to  be  a  pair  and 
numbers  with  prefix  signs  are  returned.  If  the  number  of 
nibbles  in  "Xstring"  is  not  correct,  it  is  simply  filled  with 
"0"x  to  the  left  or  cut  off,  so  that  no  prefix  expansion  takes 
place. 


Example:      say  x2D("0D" ) 

say  X2D("FFFF") 
say  X2D("FFFF° ,4) 
say  X2D("FFFF",6) 


==>   13 
==>   65535 
==>   -1 
==>   65535 
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IADDLIBQ 


] 


Syntax:         ADDLIB  (name, priority  [ ,  of  f  set,  version] ) 

Adds  a  function  library  or  an  external  function 
environment  to  the  library  list  that  is  managed  by  the  Rexx 
Master  process.  "Name"  is  either  the  full  name  of  a  function 
library  that  is  located  on  the  logical  device  LIBS:,  or  the 
name  of  a  Public  Message  Port  that  belongs  to  a  function 
environment.  "Priority"  determines  the  search  order  for 
called  functions  and  must  be  an  integer  between  -100  and 
100.  Usually  0  is  useful. 

The  arguments  "offset"  and  "version"  refer  only  to  libraries 
and  are  necessary  to  open  one.  "Offset"  indicates  the  entry 
point  for  the  query  function  of  the  library  (usually  -30)  and 
"version"  takes  a  certain  version  number  the  library  must 
minimally  achieve  (usually  0). 

The  function  returns  a  Boolean  result  if  everything  is  in 
order.  This  does  not  mean  that  the  library  is  available  and 
the  program  does  not  try  to  load  it  until  the  first  command 
occurs.  An  equivalent  Message  Port  is  also  not  located 
until  later. 

Example:       if  ADDLIB ("rexxsupport. library " ,0, -30,0)    then 
say    "OK!" 


IADDRESSQ" 


J 


Syntax:         ADDRESS  ( ) 


Returns  the  name  of  the  message  port  to  which  external 
commands  can  be  sent.  The  function  SHOW()  can  test  if  the 
port  is  available. 


Example:       say  address  () 


=>  rexx 
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IARGQ 


Syntax:         ARG  (  [ number  [ ,  { "  E "  I  "  O " }  ]  ] ) 

Without  arguments,  ARG()  returns  the  number  of 
arguments  that  were  passed  to  a  program  or  a  sub-routine. 
If  a  "number"  is  entered,  the  argument  string  is  returned  or, 
if  that  is  not  available,  a  null  string. 

If  one  of  the  options  for  "Exists"  or  "Omitted"  is  left  out,  the 
argument  is  tested  for  the  other  and  a  Boolean  result  is 
returned. 

Example:       I*   Arguments  given:  ("Rose",, -5)  */ 

say  ARG()  ==>  3 

say  ARG (3)  ==>  -5 

say  ARG (2, "E")  ==>  0 


IDATEQ 


Syntax:         DATE  ( option  [ ,  date  [ ,  { 1 1  S }  ]  ]  ) 

Returns  the  current  system  date  in  the  desired  form.  (A 
"normal"  format  is  used  if  the  function  is  called  without  an 
argument.)  Supported  options  are: 


Base  date: 

Century: 

Days: 

European: 

Internal: 

Julian: 

Month: 

Normal: 

Ordered: 

Sorted: 

USA: 

Weekday: 


Days  since  January  1, 0001 

Days  since  the  beginning  of  the  century 

Days  since  the  beginning  of  the  year 

Date  in  the  form  DD/MM/YY 

System  days  (since  January  1, 1978) 

Date  in  the  form  YYDDD 

Month  in  English  (upper  and  lowercase  letters) 

Date  in  the  form  DD  MMM  YYYY 

Date  in  the  form  YY/MM/DD 

Date  in  the  form  YYYYMMDD 

Date  in  the  form  MM/DD/YY 

The  weekday  in  English  (upper  and  lowercase) 


A  specific  date  can  be  requested.  To  do  this,  the  argument 
"date"  is  given  as  system  days  or  as  a  "sorted  date"  in  the 
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form  YYYYMMDD;  in  the  latter  case  a  third  argument  "S" 
(for  "sorted")  must  be  supplied. 


Example: 


say  DATE ( ) 

say  DATEC'W") 

say  DATE ( " W " , DATE ( " I " ) +3 ) 

say  DATE ("J", 19800517, "S") 


==>  22  Jan  1991 
==>  Tuesday 
==>  Friday 


Caution: 


In  VI. 14  no  date  before  system  date  0,  January  1  1978  can 
be  entered  in  this  manner. 


IerrortexTq" 


Syntax:         ERRORTEXT  (number) 

Returns  an  error  message  for  the  given  ARexx  error 
number.  If  "number"  is  not  a  valid  error  number,  the 
message  "Undiagnosed  internal  error"  is  returned. 
Unfortunately,  ARexx  doesn't  maintain  the  Rexx  standard 
for  error  messages,  but  uses  its  own  numbers. 

Example:       say  ERR0RTEXT(15)         ==>  Function  not   found 


IEXPORTQ 


Syntax:  EXPORT(address[, [string] [, [length] [ ,padpattern] ] ) ) 

Copies  the  given  data  from  "string"  to  the  4-byte  "address" 
in  the  storage  space  that  must  have  previously  been 
reserved  with  GETSPACE().  "Length"  determines  the 
maximum  number  of  characters  to  be  copied,  "padpattern" 
(one  byte)  is  used  to  fill  up  the  string  if  it  isn't  long  enough. 
The  default  value  is  "00"x.  You  can  use  this  function  to 
enter  an  address  and  length  in  order  to  delete  from  the 
storage  area,  or  to  initialize  with  "padpattern".  The  returned 
value  is  the  number  of  characters  actually  copied. 

Caution:  This  function  can  be  used  to  overwrite  any  storage  areas, 
which  can  lead  to  fatal  error.  Never  use  EXPORT()  with  a 
reserved  stack  unless  you  know  exactly  what  you  are 
doing.  Secure  your  program  scripts  against  the  common 
error  of  overstepping  reserved  space.  Also,  during  copy 
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operations,  task-switching  is  interrupted.  With  large 
amounts  of  data  (if  possible)  copy  several  sub-strings,  so 
multitasking  operations  aren't  interrupted  for  too  long. 

Example:         say  EXPORT("0024   DDB0"x,  "The  Rose   is   red")      ==>   15 
say  EXPORT("0006   0000"x, , 640, *FF"x)  ==>   640 

IFREESPACEQ  1 

Syntax:         FREESPACE  (  [address ,  length]  ) 

Returns  the  storage  area  of  the  Rexx  master  procedure.  If 
you  specify  the  4-byte  address  with  which  the  block  was 
designated  using  GETSPACE()  earlier,  its  length  (a  multiple 
of  16)  is  returned.  The  function  FREESPACE()  with  false 
entries  (and  sometimes,  in  VI.  14,  even  correct  ones)  quickly 
allows  the  computer  to  get  caught  on  the  problem  or  run 
through  endless  loops.  The  returned  value  is  not  a  Boolean 
result,  as  the  documentation  states,  instead  it's  the  size  of 
the  free  space  under  the  control  of  the  Rexx  master 
procedure  (and  that  result  often  contains  errors).  A  call 
without  arguments  returns  the  true  size  of  the  storage 
space  being  managed  by  the  Rexx  master  procedure.  Since 
the  storage  area  is  automatically  returned  after  the  program 
ends,  calling  FREESPACE()  is  only  necessary  when  you 
may  run  out  of  space. 

Example:       say  FREESPACE("0002fa44"x,32)  ==>  848    ? 

IGETCLIPQ  1 


Syntax:         GETCLlP(name) 

Searches  the  Clip  list  for  "name"  and  returns  the 
corresponding  character  string.  Upper  and  lowercase 
spelling  are  differentiated.  If  there  is  no  entry,  an  empty 
string  is  returned. 

See  also:       SETCLIP() 

Example:       I*   "DaData"  contains  "The  Rose  is  flighty"  */ 
say  GETCLIPC DaData")  ==>   The  Rose  is  flighty 
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IgetspaCeQ" 


Syntax:         GETSPACE  ( length) 


IHASHQ 


Syntax: 


Example: 


Reserves  a  stack  of  "length",  managed  by  the  Rexx  master 
procedure.  It  returns  a  4-byte  address,  indicating  the 
beginning  of  the  reserved  storage  area,  which  is  not 
deleted.  "Length"  is  rounded  up  to  the  next  multiple  of  16. 

Stacks  reserved  with  GETSPACE()  are  automatically 
returned  to  the  Rexx  master  procedure  at  the  end  of  the 
program,  so  external  programs  should  not  access  this 
storage  area.  In  the  "rexxsupportlibrary",  a  function  called 
ALLOCMEM()  requests  storage  space  directly  from  the 
system;  it  can  be  necessary  in  such  cases. 


Example:       say  C2X  (getspace  (64)) 


==>   002937F8    ? 


HASH (string) 

Returns  the  hash  value  of  "string"  as  a  decimal  number.  The 
hash  value  is  the  lowest  byte  of  the  sum  of  all  ASCII  values 
contained  in  the  string. 


say  HASH ("A") 
say   HASHC'AAAA") 


==>  65 
==>  4 


IIMPORTQ 


: 


Syntax:         IMPORT  (address  [ ,  length] ) 

Reads  data  from  the  given  4-byte  storage  address.  If  no 
length  is  specified,  the  process  ends  at  the  first  "00"x, 
which  is  practical  for  reading  C  strings. 


Example: 


!  practical  for  reading  C  strings. 

say  IMPORT ("00FC0038"x, 9)     ==>  Amiga  ROM 
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jPRAGMAQ" 


Syntax:  PRAGMA  ( opt i on  [ ,  va lue  ]  ) 

Various  system-specific  parameters  of  your  own  program 
can  be  determined.  The  options  are: 

Directory:  A  new  current  directory  can  be  set  for  the  running 
procedure.  The  function  returns  the  full  path  name  of  the 
previously  current  directory;  it  can  be  saved  in  order  to 
restore  the  old  settings  later.  "Value"  must  be  a  valid  Amiga 
DOS  path  name  or  be  omitted.  In  the  latter  case,  only  the 
current  setting  is  returned.  If  the  path  is  not  valid  or  not 
given,  a  null  string  is  returned. 

Id:  Returns  the  4-byte  pointer  to  the  Task  Control  Block 

structure  of  the  current  program  as  an  8-byte  hexadecimal 
string.  Using  this  address,  you  can  create  independent  file 
or  port  names  specific  to  the  appropriate  program  call. 

Priority:  A  new  task  priority  can  be  given  to  the  procedure  with  this 
option.  The  function  then  returns  the  previous  priority 
setting.  Its  "value"  must  be  a  whole  number  between  -128 
and  127;  no  ARexx  program  should  run  with  a  higher 
priority  than  the  ARexx  main  program,  which  is  usually  set 
at  4.  "Value"  must  always  be  specified,  which  means  that  a 
priority  cannot  be  queried  without  possibly  changing  it.  If 
no  area  check  is  taking  place,  the  lowest  byte  of  the  given 
number  is  used. 

Window:  This  option  changes  the  window  pointer  of  the  task  control 
block  in  the  running  program.  For  "value",  valid  keywords 
are  "Work  Bench"  and  "Null".  By  entering  "null",  you  can 
prevent  requests  from  being  sent  the  Workbench  by  DOS 
calls  (such  as  Insert  Volume  ...  etc.).  At  this  point,  only 
"null"  is  recognized;  all  others  (including  an  omitted  second 
argument)  lead  to  the  default  setting  "WorkBench".  The 
function  also  always  returns  a  1  to  indicate  successful 
completion. 
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"*". 


Defines  the  given  logical  name  "value"  as  the  current  ("*") 
console  handler.  This  means  you  can  open  two  data  strings 
in  one  window.  The  result  is  a  Boolean  result. 


Example: 


say  PRAGMA ("P", -2) 

say  PRAGMAC'D") 

say  PRAGMAC'D" ,  "dfO:c) 

say  PRAGMA ("I") 

say  PRAGMA ( " W" , "Null " ) 

say   PRAGMA (»*«," STDIN" ) 


=>    0 

=>   Boot_2.X:    ? 

=>  ARexxl.14:    ? 

=>   0028FE08    ? 

=>    1 

=>    1 


IREMLIBQ 


Syntax:         REML I B  ( name ) 

Removes  an  entry  with  the  given  name  from  the  library  list 
managed  by  the  ARexx  master  procedure.  The  function 
returns  a  1  if  the  name  is  found  and  removed;  otherwise  it 
returns  a  0.  It  does  not  differentiate  between  libraries  and 
external  function  environments. 

See  also:       ADDLEB() 

Example:       REMLlBC'rexxsupport.  library")  ==>  1 

ISETCLIPQ  1 


Syntax: 


Example: 


SETCLIP (name [ , value ] ) 

Adds  a  "value"  (any  string)  "name"  to  the  Clip  list  being 
managed  by  the  ARexx  master  procedure.  If  an  entry 
already  exists  under  that  name,  the  contents  are  updated  to 
the  new  value  or,  if  no  "value"  is  given,  the  entire  entry  is 
deleted.  The  result  is  a  Boolean  result. 

say  SETCLIP ("Textl", "No,  no  roses")    ==>  1 
say  SETCLIP ("Textl")  ==>  \ 
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ISHOWQ 


Syntax:  SHOW(option[ ,  [name]  [, divider]  ]  ) 

Returns  the  contents  of  various  lists  being  managed  or 
used  by  the  ARexx  master  procedure.  "Option"  refers  to 
one  of  the  following  key  words: 

Clip:  Names  in  the  Clip  list. 

Files:  List  of  open  logical  filenames. 

Internal:  Internal  port  list. 

Libraries:  External  library  and  function  environment  list. 

Ports:  List  of  Public  Message  Ports,  managed  by  EXEC.  An 

unnamed  port  is  indicated  by  a  question  mark. 

If  no  "name"  is  specified,  the  function  returns  a  string  with 
entries  in  the  given  list,  separated  by  a  space  or  the  optional 
"divider".  If  "name"  is  specified,  the  corresponding  list  is 
searched  for  the  entry  and  a  Boolean  result  shows  if  it  was 
found. 


Example :       say  show  ("  p  ",,";" ) 

say  SHOW ( " C " , " Text 1 " ) 


==>REXX ; DMouse ; Workbench 
==>  1 


ISOURCELINEQ 


Syntax:  SOURCELINE  (  [  1  ine  ]  ) 

Returns  a  string  representing  the  given  line  of  the  current 
program.  If  "line"  is  omitted,  the  number  of  lines  in  the 
program  is  returned.  The  function  can  be  used  to  display 
comment  line",  used  as  a  help  feature. 

Example:       say  sourceline ( )        ==>  35  ? 

say  SOURCELINE ( 1 )   ==>  /*  A  test  program  */  ? 
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ISTORAGEft 


] 


Syntax:  STORAGE ( [address] [ , [string] [ , length [ , pad] ] ] ) 

Writes  "string",  starting  at  the  given  address,  directly  to  the 
main  storage  area.  If  "length"  is  specified,  the  actual  length 
of  the  string  is  disregarded  and  only  that  number  of  bytes 
written;  in  this  case  the  "string"  is  either  shortened  on  the 
right  or  padded  with  empty  space  (or  the  given  "pad").  The 
result  string  is  the  previous  contents  of  the  affected  stack 
that  can  be  saved  and  restored  later. 


Example: 


If  the  function  is  entered  without  arguments,  it  returns  the 
total  available  storage  space. 

say  STORAGE ()  ==>1846536    ? 

before  =  STORAGE( "00040000"x, after) 


ISYMBOLQ 


Syntax: 


SYMBOL (name) 

Checks  if  the  argument  is  a  valid  ARexx  symbol.  If  not,  it 
returns  the  string  "BAD".  If  it  is  a  valid  but  un-initialized 
symbol,  the  result  is  "LIT",  and  if  the  symbol  has  already 
been  assigned  a  value,  the  answer  is  "VAR". 


Example: 


say  SYMBOL ("$%&") 
say  SYMBOL ("before") 
say  SYMBOL ( "when" ) 


==>  BAD 
==>  VAR 
==>   LIT 


ITIMEQ 


Syntax:         TIME  ( [option] ) 

Without  an  optional  keyword,  TIME  returns  the  current 
system  time  in  24-hour  format,  in  the  form  "hh:mm:ss". 
Possible  options  are: 

Civil:  American  12-hour  format  in  the  form"[h]h:mmxx",  where 

"xx"  is  either  "am"  or  "pm".  The  hour  does  not  receive  a 
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Elapsed: 

Hours: 

Minutes: 


leading  zero,  and  the  minute  is  the  current  minute,  not  (as  is 
usually  the  case)  the  next  minute. 

The  number  of  seconds  and  hundredths  of  a  second  that 
have  passed  since  an  initial  call  to  the  internal  timer  with 
"Elapsed"  or  "Reset". 

The  number  of  hours  since  midnight  without  a  leading  zero. 

The  number  of  minutes  since  midnight  without  a  leading 
zero. 


Normal:         Returns  the  default  setting  (the  same  result  as  calling  the 
function  without  an  argument). 

Reset:  Returns  the  number  of  seconds  and  hundredths  of  a 

second  since  an  initial  query  to  the  internal  timer  using 
"Elapsed"  or  the  last  "Reset",  and  simultaneously  resets  the 
timer. 

Seconds:        The  number  of  seconds  since  midnight  without  leading 
zeros. 


Example: 


say  TIMEO 
say  TIMEC'R") 
say  TIME("E") 


=>   18:35:22    ? 
=>   0    ? 
=>   2.12    ? 


ITRACEQ 


Syntax:         TRACE  (option) 

With  no  argument,  this  function  returns  the  current  TRACE 
setting.  All  valid  TRACE  keywords  can  be  specified  as 
options  (numbers  are  not  allowed,  but  "?"  and  "!"  are).  The 
TRACE()  function  changes  the  TRACE  mode,  even  during 
interactive  tracings,  when  all  other  TRACE  commands  are 
ignored.  The  result  is  always  the  last  setting  that  can 
thereby  be  saved  and  restored  later. 


Example:      say  trace  0 


==>   N 
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IVALUEQ 


Syntax:         VALUE  ( name ) 


Returns  the  contents  of  the  given  ARexx  symbol,  which 
must  be  a  valid  symbol.  This  function  is  used  when  the 
variable  name  itself  is  a  variable,  as  a  whole  or  partially. 

Example:       /*  Situation:  DROP  q5,  155=8;  n=5;  Rose="n"*/ 
say  VALUE ("Rose")  ==>  n 

say  VALUE (Rose)  ==>  5 

say  VALUE ("q"n)  ==>  Q5 

say  VALUE("l"n| In)  ==>  8 
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8.    Special  Features 


Rexx  contains  several  powerful  special  features  that  may  be  unfamiliar  to 
users  of  other  programming  languages.  The  most  important  ones,  parsing 
data  and  tracing  programs,  are  discussed  here. 


8.1      Parsing  Strings  with  Templates 


The  ARexx  instruction  PARSE  (and  its  two  abbreviations  ARG  and 
PULL)  split  an  entry  according  to  a  "template"  and  direct  the  results  to 
variables.  This  feature  is  especially  useful  when  you  are  using  ARexx  as 
a  script  language  on  the  Amiga,  since  many  commands  that  were  not 
conceived  for  automatic  processing  deliver  cryptic  return  values  that  do 
not  conform  to  any  formatting  standards.  The  CLI  script  language  offers 
some  help  in  parsing  argument  lines  (with  ".")  and  some  command  line 
syntheses  (using  "CLIs  LFORMAT"),  but  both  of  them  fail  difficult 
parsing  tasks. 

The  previous  description  of  PARSE  is  a  short  explanation  of  its  most 
important  capabilities.  The  following  is  a  complete  process  description: 

A  template  consists  of  two  elements,  symbols  which  are  assigned  values 
during  the  operation,  and  markers  to  indicate  a  position  within  the  source 
string.  Valid  markers  are:  strings,  operators  such  as  "+","-"  and  "=",  closed 
parentheses,  and  commas.  Using  the  template,  a  beginning  and  end 
position  is  determined  within  the  source  string  for  every  target  symbol. 
The  corresponding  portion  of  the  string  is  then  assigned  to  the  symbol. 
There  are  three  types  of  markers:  "absolute",  which  indicate  an  exact 
position  in  the  source  string,  "relative",  which  indicate  a  positive  or 
negative  offset  from  the  present  position,  and  "pattern"  which  indicates  a 
position  by  comparing  the  given  pattern  to  the  source  string.  In  a 
template,  the  target  of  the  sub-string  is  a  variable  symbol  or  a  specific 
goal  (or  a  period);  the  corresponding  value  is  not  assigned  to  the  target. 
Variables  in  a  template  always  receive  a  new  value,  even  if  the  source 
data  do  not  contain  enough  words.  Any  remaining  variables  are  set  to  0. 
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Valid  template  elements 

symbols:  A  symbol  may  be  a  target  or  a  marker.  If  it  immediately 

follows  one  of  the  valid  operators  ("+","-"  or  "="),  its 
value  (which  in  this  case  must  be  an  integer)  is 
interpreted  as  a  relative  or  an  absolute  position.  If  a 
symbol  appears  in  parentheses,  its  value  is  a  comparison 
pattern.  If  neither  condition  is  true,  it  must  be  a  variable, 
to  which  a  value  is  assigned. 

strings:  A  string  is  always  a  comparison  pattern. 

parentheses:  If  a  symbol  appears  in  parentheses,  it  is  a  comparison 
pattern.  Normally,  a  variable  symbol  is  used;  a  constant 
value  is  easier  to  display  within  a  string. 

operators:  The  characters  "+","-"  and  "=",  followed  by  a  symbol 

(which  must  represent  an  integer),  indicate  index 
positions  in  the  source  string.  "+"  and  "-"  indicate 
relative  positions,  "="  indicates  an  absolute  position. 

commas:  A  comma  separates  multiple  templates.  If  several 

templates  follow  one  another,  the  interpreter  looks  for  a 
new  source  string.  In  some  source  options,  it's  identical 
to  the  last.  With  the  options  ARG,  EXTERNAL  and 
PULL,  a  new  string  is  created;  the  same  is  true  for  the 
option  VAR,  if  the  contents  of  the  variables  has 
changed. 

periods:  A  period  serves  as  a  dummy  value  and  operates  as  a 

target  for  a  sub-string  which  is  to  be  discarded. 

Each  character  in  the  source  string  has  an  index  number,  from  1,  for  the 
first  character,  to  the  length  of  the  string  plus  1  (the  end  of  the  string).  If 
the  limit  is  exceeded,  the  current  position  is  set  at  the  limit.  A  sub-string, 
defined  by  two  indices,  always  contains  the  character  of  the  first  index 
and  continues  up  to  the  second.  The  indices  3  and  8  would  define  a  sub- 
string of  the  characters  3  to  7.  If  both  indices  are  equal,  or  the  second  is 
smaller,  the  remainder  of  the  source  string  is  defined  by  the  pair.  The 
command: 

PARSE  value   "bla  bla  bla"   WITH   1  all   1  Wordl   Word2   Word3 
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assigns  the  entire  string  to  the  variable  "all",  after  which  each  word  is 
parsed  into  equivalent  variables.  When  a  pattern  is  compared  to  the 
source  string,  the  position  of  the  first  character  matching  the  pattern  is 
the  new  index  and  the  pattern  is  removed  from  the  source  string.  This 
means  that  the  source  string  is  altered  in  the  process  of  this  operation. 

The  evaluation  goes  from  left  to  right  in  the  template.  At  the  beginning, 
the  source  string  index  is  set  to  1.  Whenever  a  marker  appears  in  the 
template,  its  position  becomes  the  current  one.  Whenever  a  target  is 
found,  the  program  searches  for  the  next  object  in  order  to  determine  the 
length  of  the  sub-string  the  target  expects.  If  the  next  object  is  a  target, 
the  source  string  is  divided  into  words.  The  process  does  not  end  until 
the  template  has  been  completely  evaluated.  If  the  source  string  is  fully 
parsed,  remaining  targets  receive  null  strings. 

8.1.1  Examples  of  Parsing 

All  of  the  following  examples  were  given  the  source  string. 

"One  believes,   one  knows,  but  know:  one  believes." 

Please  notice  the  double  space  after  the  first  comma  and  after  "but". 
Comparison  patterns 

If  there  is  a  string  in  the  template,  the  source  string  is  scanned  from  left  to 
right  (after  the  first  appearance  of  the  sequence  of  characters).  If  it's 
found,  it's  removed  from  the  source,  and  the  index  is  placed  on  the  first 
character  after  the  sequence.  If  there  is  no  matching  string,  the  index  is 
placed  behind  the  last  character  of  the  source.  Given  the  following 
template: 

Tl    " , "    T2    " , "    REST 

the  source  string  would  be  parsed  as  follows: 

Tl  =  "One  believes" 

T2  =  "  one  knows" 

REST  =  "  but   know:  one  believes." 

The  following  template  shows  what  happens  if  there  is  no  agreement: 
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Tl    " ,  "    T2    " , "    T3    " ,"    REST 


because  no  third  comma  is  found,  T3  receives  the  rest  of  the  string  and 
REST  receives  nothing. 

Tl  =  "One  believes" 

T2  =  "  one  knows" 

T3  =  ■  but   know:  one  believes." 

REST  =  "" 

If  REST  previously  contained  another  value,  it's  now  lost,  since  the 
variable  received  an  empty  string.  Comparison  patterns  may  be  variable. 
In  this  case,  the  corresponding  symbol  must  be  indicated  with  closed 
parentheses.  (In  ARexx,  this  method  always  forces  an  analysis  of  a 
symbol,  which  makes  the  key  word  "VALUE"  unnecessary  in  some 
situations,  but  not  with  the  PARSE  command).  The  corresponding 
variable  can  be  previously  defined  (further  to  the  left)  in  the  same 
template.  This  is  a  possible  application: 

command  =  "\SEARCH\Typignmistake\CW" 

parse  var  command  divid  2  instruction  (divid)  string  (divid)  option 

In  this  case,  the  first  character  of  "command"  is  the  separator  used  to 
parse  the  rest  of  the  string. 

Parsing  into  words 

If  several  targets  follow,  the  source  string  is  parsed  into  words.  (Or  it 
could  be  a  sub-string  of  the  source,  if  it  appears  before  or  after  the  target 
patterns  have  been  specified).  Each  target  from  left  to  right  is  assigned  a 
word.  Empty  space  between  words  is  dropped.  If  several  words  are  left 
over,  the  last  target  receives  the  remainder,  including  the  empty  space 
contained  in  it.  For  example: 

Wl   W2   W3    REST    " : " 

leads  to  the  result: 

Wl  =  "One" 

W2  =  "believes, " 

W3  =  "one" 

REST  =  "  knows,  but  know" 


558 


8.1  Parsing  Strings  with  Templates 


As  you  can  see,  the  remainder  of  the  string  contains  the  leading  space  in 
the  source.  (ARexx  does  not  behave  entirely  according  to  Rexx 
specifications  here:  the  space  should  be  removed.)  Please  note  that  a 
template  of  the  form: 

Wl    -    "    W2    "    "    W3    "    "    REST    ■ : " 

which  refers  to  the  empty  space  as  a  comparison  pattern,  leads  to  a 
different  result: 

Wl  =  "One" 

W2  =  "believes,  " 

W3  =  ■• 

REST  =  "one  knows,  but  know" 

As  expected,  Wl  received  the  first  word,  W2  the  second  word,  between 
the  first  two  spaces,  but  what  about  W3?  In  this  example,  it's  assigned 
the  entire  string  between  the  second  and  third  empty  spaces.  A  null 
string  was  correctly  assigned,  since  they  immediately  follow  one  another. 
Since  the  comparison  removes  the  empty  space  in  front  of  "one",  "REST" 
no  longer  contains  a  leading  space. 

A  period  has  special  meaning  in  parsing  words:  it  works  as  a  target,  just 
as  a  variable  symbol,  but  the  value  assigned  to  it  is  discarded.  The  period 
is  used  to  ignore  unnecessary  words  in  the  source  string.  The  template: 

.     .     .    W4    . 

would  extract  only  the  fourth  word  from  the  source  string,  in  this  case, 
"knows,"  and  assign  it  to  the  variable  W4. 

Parsing  by  position 

In  this  process,  the  source  string  is  cut  up  at  certain  character  positions. 
The  appropriate  index  values  are  entered  as  whole  numbers: 

Tl   10  T2   20   T3 

returns  from  the  original  example  string: 


559 


8.  Special  Features 


Tl  =  "One  believ" 

T2  =  "es,   one  " 

T3  =  "knows,  but   know:  one  believes." 


The  target  Tl  receives  the  characters  1  to  9,  T2  the  characters  from  10  to 
19  and  T3  is  assigned  the  rest. 

This  example  used  absolute  positions.  Use  prefix  operators,  ("+"  or  "-")  to 
move  the  index  position  relative  to  the  last  position.  For  example: 


numbers  =  "1234567890" 

parse  var  numbers  2  Zl  +4  -1  Z2  -2  Z3  +5 


leads  to  the  following  result: 


Zl 

=   "2345" 

Z2 

=   "567890" 

Z3 

=   "34567" 

First,  Zl  receives  four  characters  of  input,  starting  from  the  second  place. 
Then,  the  index  is  moved  back  by  one  character  ("-1"),  and  the  digit  "5" 
reappears  in  Z2.  From  "-2",  the  absolute  position  3  is  calculated.  The 
second  index  for  Z2  is  smaller  than  the  first.  This  means  that  the  rest  of 
the  source  string  is  assigned  to  Z2.  Finally,  the  Z3  target  receives  five 
characters  ("+5")  starting  from  the  last  position  (3). 

Using  numeric  position  indicators,  whether  they  are  relative  or  absolute, 
you  can  read  parts  of  the  source  string  several  times,  if  necessary.  The 
following  command  string  is  also  possible: 


parse  var  numbers  Zl  1  Z2  1  Z3 


This  command  assigns  the  full  contents  of  "numbers"  to  each  of  the  three 
different  variables. 

A  numeric  position  indicator  can  be  a  variable:  for  a  relative  position,  add 
a  "+"  or  "-"  in  front  of  the  variable  symbol.  To  indicate  an  absolute 
position  place  an  equal  sign  "="  in  the  same  place;  this  differentiates  them 
from  target  symbols. 

Combined  parsing  methods 

If  a  comparison  pattern  is  directly  followed  by  a  relative  position 
indicator,  you  achieve  a  special  effect.  The  pattern,  if  found,  is  not 
removed  from  the  source  string.  The  current  position  remains  set  at  the 
first  character  of  the  pattern  string. 
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8.2     Error  Trapping  with  TRACE 

What  would  be  the  advantage  of  using  an  interpreted  language  if  there 
were  no  TRACE?  A  programmer  can  investigate  the  events  during 
program  execution;  it  makes  the  often  difficult  search  for  errors  much 
easier,  since  even  well-hidden,  minor,  logical,  program  errors  become 
apparent.  Rexx  offers  substantial  support  for  this  function.  During 
TRACE,  the  interpreter  displays  certain  program  parts  during  their 
execution.  A  line  number,  the  source  text  and  additional  information  is 
displayed.  Interpreter  behavior  is  set  with  trace  options,  that  determine 
which  program  parts  should  be  displayed.  Two  flags  control  command 
suppression  (!)  and  interactive  tracing  (?). 

Because  it  uses  "signals",  the  ARexx  program  can  recognize  certain 
synchronic  events  (i.e.,  a  "syntax  error")  or  asynchronic  events  (such  as  a 
"halt"  request).  Using  these  features,  most  error  conditions  can  be 
handled  by  the  program  and  program  aborts  can  often  be  prevented. 

8.2.1  Trace  Options 

The  following  modes  are  available: 

ALL  Displays  all  clauses  before  execution. 

BACKGROUND 

Similar  to  OFF,  except  the  tracing  cannot  be  externally 
enabled  with  the  "TS"  command. 

COMMANDS  Displays  all  command  clauses  before  they  are  passed  to 
the  external  environment.  Also,  displays  return  codes 
not  equal  to  0. 

ERRORS  Displays  commands  that  pass  a  return  code  not  equal  to 

0  after  execution. 

INTERMEDIATES 

Displays  all  clauses,  sub-totals  (including  variable 
contents),  a  final  form  of  concatenated  symbols,  and 
results  of  function  calls. 


561 


8.  Special  Features 


LABELS 


NORMAL 


OFF 


RESULTS 


SCAN 


Displays  all  jump  markers. 

Displays  commands  with  return  codes  that  exceed  the 
current  failure  level  after  their  execution,  and  presents 
an  error  message.  This  is  the  default  setting. 

Switches  all  tracing  off. 

Displays  all  clauses  before  their  execution  and  presents 
the  result  of  every  expression.  Values  assigned  to 
variables  with  ARG,  PARSE  or  PULL  are  also 
displayed. 

Displays  all  clauses  and  checks  them  for  errors,  but  does 
not  actually  execute  them.  This  mode  can  be  set  on  with 
the  TRACE  command  or  the  internal  function  TRACE(). 
It  can  be  engaged  at  appropriate  spots  in  the  program, 
so  that  previously  tested  parts  are  not  re-tested.  The 
RESULT  option  is  usually  effective  for  most  error 
trapping  situations. 


8.2.2  TRACE  Output 


Each  line  is  indented  on  the  screen  to  represent  the  level  of  nesting 
applicable  to  the  clause.  At  the  beginning,  there  is  the  line  number  in 
which  the  clause  appears  in  the  program  and  then  a  three  character 
marker,  which  shows  the  meaning  of  the  displayed  line.  Sub-totals  or 
expressions  appear  in  quotation  marks  so  prefixes  and  spaces  are  easily 
recognized. 


Code 

Meaning  of  code 

program  text  of  a  clause 

+++ 

command  or  syntax  error 

>C> 

expanded  form  of  a  compound  symbol 

>F> 

result  of  a  function  call 

>L> 

jump  marker  (literal  or  constant  value) 

>0> 

result  of  a  dyadic  operation 

>P> 

result  of  a  prefix  operation 

>U> 

uninitialized  variable 

>v> 

value  of  a  variable 

»> 

result  of  an  expression 

» 

value  of  the  place  holder 
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If  the  data  stream  is  defined,  TRACE  output  is  directed  by  the  interpreter 
to  "STDERR";  otherwise  it  goes  to  STDOUT,  in  addition  to  the  display 
and  normal  program  output. 

In  some  cases  "STDOUT"  is  not  defined,  for  example,  if  a  macro  program 
is  started  without  opening  an  I/O  window.  To  enable  tracing  for  such 
programs,  a  global  trace  window  can  be  opened  in  the  Rexx  master 
procedure.  For  every  program  in  which  the  "STDERR"  is  not  defined, 
this  window  becomes  the  output  target  for  "STDERR". 

With  the  commands  TCO  and  TCC,  a  global  tracing  window  is  opened 
and  closed.  Before  it's  closed,  all  output  of  all  programs  must  be  returned 
to  its  beginning  status.  The  tracing  window  can  also  be  directed  with 
messages  from  application  programs.  During  interactive  tracing,  this 
window  is  used  for  keyboard  entry.  Since  all  active  programs  share  one 
window  for  trace  output,  following  more  than  one  simultaneous 
executing  program  is  not  recommended,  since  the  result  might  be 
confusing. 

8.2.3  Command  Suppression  in  ARexx 

Programs 

Suppressing  commands  is  useful  when  an  ARexx  program  should  not 
pass  commands  to  external  environments  without  prior  testing.  If  one 
uncontrolled  program  starts  sending  unnecessary  commands  to  DOS  (for 
example,  to  delete  files),  there  may  be  disastrous  results. 

ARexx  includes  a  trace  mode  in  which  these  commands  are  only 
displayed.  The  return  code  is  zero  (which  would  usually  be  returned  if 
the  command  was  successful)  and  the  program  continues.  Commands 
entered  during  interactive  tracing  are  always  executed,  but  they  do  not 
affect  the  value  of  the  return  code. 

Command  suppression  is  controlled  using  exclamation  marks,  either 
alone  or  in  front  of  a  trace  option,  to  toggle  these  functions  on  and  off.  If 
the  trace  option  "OFF"  or  "BACKGROUND"  has  been  selected,  then 
command  suppression  is  disabled. 
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8.2.4  Interactive  Tracing 


During  interactive  tracing  you  may  enter  single  clauses  during  program 
execution  in  order  to  test  variable  contents,  to  change  them  to  enter 
commands  or  to  direct  branching  and  loops.  You  can  enter  as  many 
commands  as  you  want  with  the  same  limitations  as  interpreter 
commands,  for  example,  DO-END  constructions  must  appear  in  one  line. 

Any  trace  mode  can  be  used  interactively.  The  interpreter  waits  after 
each  displayed  clause  and  requests  information  with  the  message  ">+>". 
As  a  programmer  you  have  three  options: 


•  Press  [Enter!,  entering  an  empty  line,  and  the  program  proceeds  to 
the  next  trace  output.  The  "ALL"  mode  executes  the  program  step 
by  step  by  pressing  the  [Enterl  key. 

•  Enter  an  equal  sign  (=)  and  the  last  clause  is  repeated.  This  is  only 
useful  if  a  change  has  been  made,  a  correction  of  variables; 
otherwise  the  result  will  always  remain  the  same. 

•  Another  command,  which  will  be  immediately  executed  if  it's  ARexx 
code.  Where  the  program  is  interrupted  depends  on  the  trace  mode 
you  have  chosen;  the  interpreter  only  stops  after  the  clauses  it's 
asked  to  display.  There  are  some  commands  that  cannot  be 
executed  a  second  time,  at  which  the  interpreter  will  not  stop.  They 
are:  CALL,  DO,  ELSE,  IF,  THEN  and  OTHERWISE.  Also,  the 
interpreter  will  not  stop  after  a  clause  that  causes  an  error. 

Interactive  tracing  is  controlled  with  the  question  mark,  which  can  occur 
alone  or  in  front  of  a  trace  option.  Each  appearance  of  the  question  mark 
toggles  interactive  tracing  on  or  off.  For  example,  the  command  "TRACE 
?I",  to  activate  interactive  tracing  and  set  "INTERMEDIATES"  tracing 
on,  begins  a  sub-total  display.  During  interactive  tracing  further 
instructions  that  call  trace  are  ignored,  so  you  cannot  accidentally  exit 
trace  mode. 

Errors  in  the  execution  of  lines  entered  interactively  are  displayed  but  do 
not  lead  to  a  program  stop.  Also,  during  interactive  tracing,  SIGNAL 
interrupts  are  blocked.  This  is  to  avoid  a  command  error  or  prevent 
another  SIGNAL  condition  from  immediately  branching  out  to  an 
equivalent  label.  Such  a  jump  cannot  be  un-done  and  would  normally 
prevent  a  programmer  from  taking  interactive  measures  when  an  error 
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occurs,  thus  creating  an  uninterruptable  infinite  loop.  If  a  command  with 
the  form  "SIGNAL  Label"  is  interactively  entered,  the  jump  is  executed, 
and  further  interactive  entries  are  discarded. 

Individual  interrupt  flags  can  still  be  set  using  the  SIGNAL  command,  or 
they  can  be  deleted;  they  will  not  work  until  normal  program  execution 
resumes. 

The  trace  mode  you  enter  last  is  retained  through  sub-routines  that  you 
are  unable  to  see.  At  the  beginning  of  an  uninteresting  sub-routine 
tracing  with  "RESULTS",  enter  "TRACE  OFF".  When  the  sub-routine 
ends,  the  old  setting  is  automatically  restored.  The  Rexx  master 
procedure  manages  the  "external"  trace  flag,  with  which  running 
programs  can  be  externally  set  to  interactive  tracing. 

This  flag  is  set  with  the  CLI  command  "TS".  All  running  programs  not  set 
to  interactive  tracing  immediately  start  to  trace,  even  programs  that  start 
after  the  command.  The  trace  option  defaults  to  "RESULTS"  if  the  modes 
"INTERMEDIATES"  or  "SCAN"  were  not  previously  set;  otherwise  they 
remain  unchanged.  This  flag  can  control  programs  that  have  run  out  of 
control,  are  caught  in  endless  loops,  or  will  not  accept  any  entry.  Set  the 
display  to  interactive  mode  from  the  outside  and  perhaps  you  can 
recognize  the  problem  and  fix  it  more  quickly.  The  disadvantage  to  this 
arrangement  is  that  this  flag  influences  all  ARexx  programs.  If  other 
programs  do  not  have  their  own  10  channels,  and  the  global  tracing 
window  is  used  to  do  the  trace,  the  output  to  this  window  is  hard  to 
interpret.  The  tracing  flag  is  set  off  with  the  CLI  command  TE.  When 
individual  programs  notice  that  the  trace  mode  is  no  longer  on,  they  also 
change  the  trace  mode  to  "OFF".  Programs  whose  trace  mode  has  been 
set  to  "BACKGROUND"  do  not  respond  to  the  global  tracing  flag  at  all. 

8.2.5  SIGNAL  Interrupts  and  Error  Handling 

ARexx  offers  a  mechanism  which  makes  it  easy  to  recognize  errors  and 
special  program  situations  during  execution,  and  to  react  to  them  without 
halting  the  program.  If  an  interrupt  is  enabled  and  the  condition  occurs, 
program  execution  continues  at  the  appropriate  label.  Deciding  factors 
can  be  synchronic  (for  example,  syntax  errors)  or  asynchronic  (for 
example,  pressing  fctril+fcY).  These  are  called  "interrupts"  and  are 
handled  by  ARexx;  they  have  nothing  to  do  with  microprocessor 
"interrupt"  channels. 
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The  following  events  are  handled  by  ARexx:  the  description  of  the  event 
is  the  name  of  the  label  to  which  the  program  branches  if  the  event 
occurs.  A  "BREAK_C"  interrupt  branches  to  a  label  of  the  form 
"BREAK_C:".  An  interrupt  can  be  toggled  on  or  off  with  the  command 
SIGNAL.  If  the  corresponding  label  is  not  defined  and  the  condition  that 
has  been  enabled  occurs,  the  program  will  still  interrupt  and  display  an 
error  message. 

BREAK_C  fctril+fc")  break  detected  by  DOS.  If  the  interrupt  is  off, 
the  program  immediately  ends,  with  the  message 
"Execution  halted"  and  a  return  code  of  2. 

BREAK.D  fctrQ+fp)  break  detected  by  DOS.  This  is  ignored  if  the 
appropriate  interrupt  is  switched  off. 

BREAK.E  (ct7Q+(D  break  detected  by  DOS.  This  is  ignored  if  the 
appropriate  interrupt  is  switched  off. 

BREAK.F  (ctrj}+{F)  break  detected  by  DOS.  This  is  ignored  if  the 
appropriate  interrupt  is  switched  off. 

ERROR  The  return  code  of  an  external  program  is  not  "0". 

FAILURE  The  return  code  is  greater  than  the  FAITAT  setting. 

HALT  A  HALT  command  appeared  (for  example,  after  "hi").  If 

the  interrupt  is  switched  off,  the  program  ends 
immediately  displaying  the  message  "Execution  halted" 
and  a  return  code  of  2. 

IOERR  DOS  has  detected  an  error  in  an  I/O  operation. 

NOVALUE  An  attempt  was  made  to  access  an  un-initialized 
variable. 

SYNTAX  A  syntax  or  execution  error  has  been  encountered.  Not 

all  such  errors  can  be  caught.  Certain  errors,  occurring 
before  a  program  begins  to  execute  commands,  and 
errors  that  are  not  recognized  by  the  external  ARexx 
interface,  belong  to  this  group. 
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When  the  corresponding  jump  occurs  as  a  result  of  the  interrupt 
condition,  all  active  command  areas,  (DO  groups,  loops  etc.)  are 
dissolved,  and  the  corresponding  interrupt  is  switched  off  again.  This  is 
necessary  to  avoid  endless  interrupt  loops.  Interrupts  within  a  function 
or  a  sub-program  do  not  effect  the  main  program. 

The  interpreter  also  sets  special  variables  when  an  interrupt  appears.  The 
variable  SIGL  contains  the  current  line  number  at  the  moment  the 
interrupt  appeared.  The  variable  RC  is  set  to  the  appropriate  error  code 
during  an  "ERROR"  or  "SYNTAX"  interrupt 

On  an  "ERROR",  a  command  code  is  returned,  which  can  usually  be  read 
as  an  error  level.  For  "SYNTAX",  the  appropriate  ARexx  error  code 
appears,  which  the  internal  function  ERRORTEXT()  translates  into 
English. 

The  main  purpose  of  interrupts  is  to  make  error  handling  easier.  After  an 
error,  you  can  branch,  to  give  more  information,  or  get  to  the  root  of  the 
condition.  Error  handling  is  often  very  important  with  the  INTERPRET 
command. 
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ARexx  runs  on  any  Amiga  running  Kickstart  Vl.l  or  higher.  It  uses  the 
IEEE  math  library  on  the  Amiga  and  for  double  precision  the 
"mathieeedoubbas.library",  which  must  be  on  the  logical  device  "LIBS:". 
The  interpreter  itself  is  in  a  library  named  "rexxsysliblibrary",  which  must 
also  be  available  there.  ARexx  programs  can  be  named  any  way  you 
want,  but  there  are  some  rules  meant  to  ensure  a  clear  overview  of  library 
contents.  It  is  customary  for  ARexx  programs  that  are  started  directly 
from  the  CLI  with  "rx"  to  end  with  the  characters  ".rexx".  Macro 
programs  that  are  to  be  started  from  certain  application  programs  should 
end  with  a  set  of  characters  specific  to  the  application.  For  example, 
ARexx  programs  that  control  CygnusEd  normally  end  with  ".ced". 
ARexx  uses  its  own  logical  device:  the  ARexx  directory.  ARexx 
searches  for  programs  first  in  the  current  directory,  then  in  the  REXX: 
directory,  if  that  was  defined  with  the  CLI  command  "ASSIGN". 

After  V2.X,  ARexx  is  part  of  the  Amiga  operating  system  and  the  Rexx 
master  procedure  is  started  in  the  normal  startup  sequence;  it  runs  in  the 
background. 


9.1      Commands 


Several  CLI  commands  belong  to  ARexx  and  must  be  located  in  the  c: 
directory  or  in  the  Arexxc:  directory  that  is  in  the  command  path.  There 
are  various  available  control  functions,  all  of  which  depend  on  sending 
the  corresponding  message  to  the  Rexx  master  procedure.  Equivalent 
functions  could  be  provided  by  an  application  program  that  works  with 
ARexx. 

I  HI  (Haltlnterpretation)l 

Syntax:  HI 

Sets  the  global  "Halt"  flag,  so  that  all  active  ARexx 
programs  receive  an  external  "Halt"  request.  All 
programs  are  immediately  interrupted,  unless  caught 
with  SIGNAL  ON  HALT.  Then  a  subroutine  branch 
would  also  eventually  interrupt  (possibly  after  some 
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fRX~ 


IRXSET 


clean-up  work).  When  all  running  programs  have 
received  the  "Halt"  command,  the  flag  is  reset. 

(RexxeXecute)l 


Syntax:  RX  name    [arguments] 

RX    string    [arguments] 

Starts  an  ARexx  program.  If  "name"  includes  a  path 
name,  ARexx  only  looks  for  the  program  there; 
otherwise  it  searches  the  current  directory  and  then  the 
REXX:  directory.  If  the  Rexx  master  procedure  is  not 
running,  it's  started  first.  Arguments  are  passed  to  the 
program  and  can  be  queried  with  ARG.  The  second 
form  previously  listed  allows  you  to  enter  a  complete 
argument  as  a  string.  Observe  correct  usage  of  string 
delimiters.  If  you  want  to  define  a  string  with  this 
program,  you  must  use  the  appropriate  other  string 
delimiter,  or  enter  the  same  delimiter  twice. 

RX  can  also  be  started  with  a  tool  or  project  icon  from 
the  workbench.  A  project  icon  for  an  ARexx  program 
can  be  defined  as  the  default  tool.  If  you  are  using  RX 
in  a  tool  icon  you  can  enter  an  argument  line  under  tool 
types  with  the  flag  "CMD=".  In  both  cases 
"CONSOLE="  can  specify  a  window. 


] 


Syntax:  RXSET  name    [value] 

Adds  a  name  and  a  corresponding  string  "value"  to  the 
clip  list.  If  "name"  already  exists,  the  old  contents  is 
discarded  and  "value"  becomes  the  new  contents.  If 
there  is  no  second  argument  the  corresponding  entry  on 
the  clip  list  is  deleted. 
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rexc 


Syntax: 


(RexxClose)l 


RXC 


prcc 


Ends  the  Rexx  master  procedure.  The  "REXX"  port  is 
immediately  deleted  from  the  list  of  active  public 
message  ports  and  the  task  is  complete  as  soon  as  the 
last  active  program  ends. 

(TracingConsoleClose)  | 


Syntax: 


TCC 


rrco 


rrE 


Closes  the  global  tracing  window  as  soon  as  no  active 
program  is  using  it. 

(TracingConsoleOpen)  | 


Syntax:  TCO 

Opens  the  global  tracing  window.  All  trace  output  is 
automatically  routed  to  this  window.  It  can  be  closed 
with  TCC.  Only  one  program  should  be  in  a  trace  mode, 
since  the  output  is  otherwise  very  confusing. 


(TraceEnd)"| 


Syntax: 


TE 


Its" 


Cancels  the  global  "Trace"  flag;  all  active  ARexx 
programs  are  switched  to  the  trace  mode  "OFF". 

(TraceStarl)! 


Syntax: 


TS 


Sets  the  global  external  "Trace"  flag,  putting  all  active 
ARexx  programs  into  interactive  trace  mode.  The 
programs  then  produce  trace  output  and  wait  after  the 
next  clause.  The  command  is  useful  if  an  ARexx 
program  is  out  of  control  and  needs  to  be  brought  back 
into  line.  The  "Trace"  flag  remains  set  until  it  is  deleted 
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with  the  "TE"  command,  so  programs  that  are  called 
later  also  go  into  trace  mode. 


I  WAITFORPORT 


Syntax:  WAITFORPORT    [-immediate]    Portname 

This  command  waits  up  to  10  seconds  for  a  message 
port  with  the  given  name  to  appear.  (Caution:  Upper 
and  lowercase  spelling  is  observed  here.) 
WAITFORPORT  returns  a  0  if  the  port  is  available, 
otherwise  a  5  (WARN).  This  is  the  best  way  to  check 
for  a  port  to  become  available  for  use  by  an  application 
you  just  started  or  by  the  Rexx  master.  The  option 
"-immediate"  overrides  the  waiting  interval  and  simply 
searches  for  the  port  once. 
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9.2      Exchanging  Data  with  the  Clip  List 

The  "clip  list"  contains  character  strings  and  a  corresponding  name  for 
each.  This  is  useful  for  data  exchange  between  different  ARexx 
programs  with  the  functions  SETCLIP()  and  GETCLIP().  To  avoid  name 
conflicts,  clip  names  should  be  specific  to  a  certain  program,  perhaps  by 
using  a  specific  name  that  is  related  to  the  program  name.  There  is  no  limit 
to  the  number  of  clips  that  can  be  saved,  except  for  system  storage 
capacity.  Beyond  data  exchange,  clips  can  also  be  used  in  other  ways. 
Since  ARexx  does  not  support  Includes,  as  other  high  level  languages 
do,  the  clip  list  can  be  used  to  emulate  this  feature,  for  more  flexibly  and 
can  be  applied  simultaneously  to  several  programs.  For  example,  flags 
that  control  several  running  programs  could  be  filed  in  the  clip  list.  A  line 
named  "Presets"  with  the  following  contents,  for  example: 

quiet=l;    speed=5;    prompt="Hi   >" 

could  with  the  command: 

INTERPRET  GETCLIP ( " Presets " ) 

be  called  by  each  program  and  used  as  a  series  of  commands,  simple 
assignments  in  this  example. 

The  Rexx  master  procedure  manages  the  clip  list  and  makes  sure  that  a 
name  only  appears  once  in  it.  In  searching  for  an  entry,  upper  and 
lowercase  letters  are  distinguished;  the  name  must  always  be  spelled 
exactly  the  same  way.  Entries  remain  available  until  a  SETCLIP()  without 
the  second  argument  deletes  them.  When  the  Rexx  master  procedure 
ends,  the  clip  list  is  discarded. 
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9.3     The  rexxsupport.library 

An  external  function  library  named  "rexxsupportlibrary",  contains 
several  functions  specifically  intended  for  the  Amiga.  It  has  the  same 
format  as  the  EXEC  function  libraries,  but  contains  additional  code  that 
is  used  by  the  interpreter  to  determine  whether  a  function  is  in  the  library 
and  then  its  offset.  This  is  the  QUERY  function.  If  you  want  to  access 
one  of  these  functions,  you  must  first  add  the  library  to  the  list  of 
libraries.  The  function  ADDLIB("rexxsupport.library",0,-30,34)  performs 
this  task;  the  corresponding  file  must  be  in  the  LIBS:  directory.  The 
priority  can  be  set  to  another  value,  but  this  does  not  make  sense  unless 
there  are  several  external  libraries.  -30  is  the  customary  offset  for  the 
query  function  and  a  version  number  (not  the  revision  number,  only  the 
whole  number  portion)  must  also  be  specified  in  order  to  make  sure  that 
the  function  is  in  the  library.  The  following  documentation  refers  to 
Version  34.9. 


9.3.1 


EXEC  Functions 

ALLOCMEM() 

CLOSEPORT0 

DELAYO 

FORBID() 

FORWARD() 

FREEMEMO 

GETARGO 

GETPKTO 

NEXTO 

NULLO 

OFFSETO 

OPENPORT() 

EXEC  Functions 


PERMITO 

REPLY() 

SHOWLIST() 

TYPEPKTO 

WAITPKTO 

DOS  Functions 

BADDR() 

DELETE() 

MAKEDIR() 

RENAME() 

SHOWDIRO 


IALLOCMEMQ" 


Syntax: 


ALLOCMEM ( Length [ , Flags ] ) 


Reserves  a  memory  area  of  the  indicated  length  from  the 
list  of  free  blocks  managed  by  EXEC  and  returns  the 
beginning  address  as  a  four  byte  string.  "Length"  is 
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rounded  up  to  the  next  multiple  of  8.  In  addition,  a  4 
byte  string  can  specify  attributes  of  the  memory  area  as 
follows: 


ANY 

"00000000"x 

any  memory  area 

PUBLIC 

"00000001  "x 

hard  disk,  freely  accessible 

CHIP 

"00000002"x 

ChipRAM 

FAST 

"00000004"x 

FastRAM 

CLEAR 

"00010000"x 

deleted  memory 

See  also: 


If  necessary,  several  flags  can  be  combined  by  adding 
the  values,  for  example,  "00010003"x  for  PUBLIC, 
CHIP  and  CLEAR.  The  default  is  "PUBLIC".  If  the  call 
fails  (e.g.,  if  there  is  no  space)  an  error  message  is 
generated. 

FREEMEMQ 


Example: 


say  C2X(ALLOCMEM(256, "00000003")) 


=>   0001DE48 


ICLOSEPORTQ 


Syntax:  CLOSEPORT  ( Name ) 

Closes  the  message  port  of  the  given  name.  The  port 
must  have  been  initialized  with  a  call  to  OPENPORT() 
by  the  same  ARexx  program  before  CLOSEPORT  has 
effect.  If  result  messages  have  arrived  and  have  not 
been  handled  yet,  they  are  automatically  answered  with 
a  return  code  10.  The  result  is  boolean. 


See  also:  OPENPORTQ 


Example:  say  CLOSEPORT ("Delaware") 


==>  1 


IDELAYQ 


Syntax:  DELAY  (Ticks) 

Waits  the  given  number  of  50ths  of  a  second  (ticks)  and 
then  returns.  You  should  always  use  this  function  when 
an  ARexx  program  should  wait  a  specific  length  of  time. 
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Until  the  length  of  time  is  passed,  the  procedure  is 
moved  to  a  status  of  "waiting"  and  does  not  use  the 
processor.  Timed  loops  are  generally  not  seen  as  useful 
for  this  purpose. 


Example: 
IFORBIDQ 


say  DELAY (200) 


==>  1  (4  seconds  later) 


Syntax: 


See  also: 


Example: 


FORBID () 

Toggles  task  switching  off  and  returns  the  current 
nesting  level  in  the  previous  call  to  FORBID()  -1  (0  after 
the  first  FORBID(),  1  after  the  second,  etc). 

Since  FORBID()  only  refers  to  the  running  task,  it 
doesn't  matter  if  a  program  ends  before  task  switching  is 
enabled  with  the  PERMIT()  function.  Before  manually 
calling  STORAGEO,  EXPORT()  and  IMPORT()  to  the 
EXEC  list  or  to  data  areas  of  other  programs  from 
ARexx  programs,  you  should  always  execute 
FORBID(),  especially  if  you  access  the  task  several 
times.  Following  these  operations,  immediately  execute 
PERMITO. 

PERMIT() 


Say  FORBID () 


=>  0 


IFORWARDQ" 


Syntax:  FORWARD  ( Addr  e  s  s ,  n ) 

Not  documented. 


IFREEMEMQ" 


Syntax:  FREEMEM  (Address,  Length) 

Releases  a  storage  area  previously  reserved  with 
ALLOCMEM().  "Address"  is  normally  the  4  byte  string 
passed  by  the  equivalent  call.  "Length"  determines  the 
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Caution: 
Example: 
IGETARGQ" 


IGETPKTQ" 


Syntax: 


size  of  the  released  area.  The  command  FREEMEM() 
cannot  be  used  to  release  memory  space  that  was 
reserved  with  the  internal  function  GETSPACE() 
through  the  Rexx  master  procedure.  The  function 
returns  a  boolean  result. 

False  arguments  immediately  lead  to  program  crash. 

say  FREEMEM("000lDE48"x,256)  ==>   1 


Syntax:  GET ARG  ( Me  s  s  age  [ ,  Ent  ry  ]  ) 

Reads  a  command  or  function  name  from  a  message  at  a 
4  byte  address  located  with  GETPKT(),  given  as 
"Message".  The  optional  "Entry"  can  be  used  with  a 
function  message  to  read  individual  argument  strings 
(max.  15). 

Example:  command  =  GETARG ( Packet ) 

function  =  GETARG ( Packet , 0 ) 
Argl  =  GETARG (Packet, 1) 


Example: 


GETPKT ( PortName ) 

Checks  if  the  message  port  with  the  given  PortName 
has  received  a  report  and  returns  the  address  of  the 
oldest  message  or  "0000  0000"x,  if  nothing  has  arrived. 
The  port  must  first  have  been  opened  by  the  same 
program  with  OPENPORT(). 

The  function  immediately  returns  a  value,  even  if  there  is 
no  report.  If  a  program  doesn't  have  anything  to  do,  it's 
not  good  to  keep  "running  to  the  mailbox",  which 
keeps  the  processor  working  overtime.  Use  WAITPKT() 
and  let  the  program  sleep  until  EXEC  hears  the  mailbox 
opening. 

Packet  =  GETPKT ("Delaware") 
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INEXTQ 


Syntax:  NEXT  (Address  [  ,0f  f  set]  ) 

Returns  the  4  byte  value,  found  at  the  given  address, 
after  adding  "Offset"  (a  positive  integer).  Use 
NEXT(Address)  to  move  forward  though  a  chained 
EXEC  list,  or  NEXT(Address,4)  to  move  in  the  opposite 
direction. 


Example: 
INULLQ 


Example: 
IQFFSETQ 


ExecBase  =  NEXT (" 00000004 "x) 
WaitingList  =  NEXT (ExecBase, 420) 


Syntax:  NULL  ( ) 

Returns  a  4  byte  Amiga  pointer  with  the  value  "0000 
0000"x. 


say  C2X (NULL ( ) ) 


==>  00000000 


Syntax:  OFFSET  (Address,  Amount) 

Calculates,  from  a  4  byte  Address  and  a  (prefixed) 
whole  number  Amount,  a  new  address. 

A  convenient  method  of  calculating  the  address  of  a 
particular  entry  in  a  structure;  this  function  avoids 
doing  various  type  conversions. 

Example:  WaitListPtr  =  OFFSET (ExecBase, 420) 

IQPENPORTQ  ~| 


Syntax:  OPENPORT  ( Name ) 

Creates  a  public  message  port  with  the  given  name.  The 
result  is  boolean.  The  function  fails  (except  in  the  case 
of  immediate  lack  of  disk  space)  if  a  port  of  the  same 
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name  has  already  been  named  or  no  further  signal  bit 
could  be  reserved.  (16  are  available,  one  is  for 
communication  with  the  master  procedure.)  The  port 
created  is  bound  to  the  global  data  structure  of  the 
program.  When  a  program  ends,  all  open  ports  are 
automatically  closed  and  outstanding  messages  are 
answered  with  a  return  code  of  10. 


See  also:  CLOSEPORTQ 


Example:  say  openport( "Delaware") 


==>  1 


IPERMITQ 


Syntax:  PERMIT  ( ) 

Toggles  task  switching  back  on.  The  result  code  is  the 
current  nesting  level  of  the  previous  FORBID()  call  -1, 
after  executing  the  function.  It  returns  -1,  if  task 
switching  is  actually  permitted  again. 


Example: 
1REPLYQ 


say  PERMIT () 


Syntax: 


REPLY ( Mes  sage , Returncode ) 

Answers  a  message  at  a  4  byte  address  with 
"Returncode",  an  integer  error  code  as  Resultl.  Result2 
(the  result  value)  is  deleted.  The  result  is  boolean. 


Example: 
ISHOWLISTQ" 


say  REPLY (Packet ,10) 


==>  1 


Syntax:  SHOWLIST(Option [ , [Name] [ , [Pad] [ , "Address" ] ] ] ) 

Shows  entries  in  various  system  lists  selected  by 
options.  Options  are: 
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Assign: 

DOS  list  of  logical  devices 

Devices: 

EXEC  list  of  physical  devices 

Handlers: 

DOS  list  of  device  drivers 

Interrupts: 

EXEC  list  of  interrupts 

Libraries: 

EXEC  list  of  open  libraries 

Memory: 

EXEC  list  of  free  storage  areas 

Ports: 

EXEC  list  of  public  message  ports 

TaskReady: 

TaskReady  list  in  EXEC 

Resources: 

EXEC  list  of  resources 

Semaphores: 

EXEC  list  of  semaphores 

Waiting: 

TaskWait  list  in  EXEC 

Volumes: 

DOS  list  of  storage  media 

If  the  first  argument  is  given,  the  names  of  the  nodes  of 
that  list  are  calculated  and  returned  in  a  string  delimited 
by  an  empty  space.  If  the  second  argument  specifies  a 
name,  the  function  returns  a  boolean  result,  showing 
whether  the  name  is  in  the  list.  Upper  and  lowercase 
writing  are  distinguished  in  this  search.  The  "Pad" 
argument  can  specify  another  character,  instead  of  a 
space,  to  separate  the  entries  in  the  result  string.  The 
key  word  "Address",  in  combination  with  a  name, 
causes  the  address  of  the  specific  node  to  be  returned, 
as  a  4  byte  pointer.  If  the  name  is  not  found,  the  pointer 
reads  "0000  0000"x.  The  addresses  of  DOS  nodes  are 
calculated  in  machine  addresses  (APTR's),  so  you  do  not 
have  to  deal  with  BCPL  pointers  here. 


Example:  say  SHOWLISTCP") 

say  SHOWLISTCP",  "REXX") 

say  C2X (SHOWLISTCP",  "REXX", ,  "A")  ) 

say  SHOWLISTCP",,"*") 


==>  rexx  ARexx  IDCMP 

==>  1 

==>  0023485A 

==>  REXX*AREXX* IDCMP 


ITYPEPKTQ" 


Zl 


Syntax: 


TYPEPKT (Message) 


Returns  the  4  byte  address  of  the  pointer  of  a  message 
sender  to  the  global  task  structure.  "Message"  is  the 
address  of  the  message,  calculated  with  GETPKTQ. 
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Example: 


say  C2X(TYPEPKT (Packet) )        ==>  0026542E  ? 


IWAITPKTQ 


] 


Syntax: 


WAITPKT(Name) 

Waits  for  a  message  to  arrive  at  the  given  message  port 
name.  The  port  itself  must  first  have  been  created  in  the 
same  program  with  the  command  OPENPORT(). 

The  boolean  result  shows  whether  a  report  was  actually 
received;  normally  the  result  is  1,  since  the  function  does 
not  return  otherwise.  The  message  must  then  be 
retrieved  with  GETPKT()  and  should  be  answered  with 
REPLY(),  so  that  the  sender  can  resume  control  over 
the  storage  area. 


9.3.2 


Example: 


call  WAITPKT  "Delaware" 


DOS  Functions 


1BADDRQ 


Syntax:  BADDR  ( BPTR ) 

Re-calculates  the  BCPL  pointer  "BPTR"  from  a  normal 
4  byte  machine  address  (APTR)  by  multiplying  it  with  4. 

Example:  say  C2X(BADDR("0000   0002"x))      ==>  00000008 


IDELETEQ 


] 


Syntax:  DELETE  (Filename) 

Deletes  a  file  or  directory.  "Filename"  is  a  complete  DOS 
path.  The  boolean  result  shows  if  the  entry  was  found 
and  deleted.  Only  one  file  at  a  time  and  only  empty 
directories  are  deleted;  wildcard  characters  (*  or  &)  are 
not  permitted. 


Example: 


say  DELETE ( " T : Rose . bak " ) 


==>  1  ? 
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IMAKEDIRQ" 


Syntax: 


MAKEDIR ( DirName ) 


Example: 


IRENAMEQ" 


Syntax: 


Creates  a  directory.  "DirName"  is  a  complete  DOS  path. 
A  boolean  result  shows  whether  the  processor  was  able 
to  create  the  directory. 


say  MAKEDIR ( "RAMtRosegarden" ) 


==>  1 


RENAME ( Al t  erName , NewName ) 


Renames  a  file  or  directory  and/or  moves  it  within  the 
same  medium  and  returns  a  boolean  result. 


Example: 


say  RENAME ("DFO: Rose", "DFO :Tulip" ) 


==>    1 


ISHOWDIRQ" 


Syntax: 


Example: 


SHOWDIR( DirName [, [{"All" I "File" | "Dir")] [,Pad] ] ) 

Returns  a  string  with  the  entries  contained  in  the 
directory  "DirName",  delimited  by  an  empty  space.  The 
second  argument  is  the  keyword,  used  to  show  all 
entries,  only  files,  or  only  directories.  The  "Pad"  can  be 
used  to  put  a  different  character  between  the  entries. 


say   SHOWDIR("DF0:C") 


==>  rx  ts  te 
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9.4     Creating  ARexx  Function  Libraries 

You  can  always  enlarge  the  scope  of  ARexx  with  supplementary 
function  libraries.  There  are  several  good  reasons  to  do  this.  In  the 
simplest  case,  you  could  have  a  desire  to  take  advantage  of  the 
mathematical  or  Amiga-specific  options  in  ARexx  with  new  functions 
you  put  together  in  a  library.  A  function  library  created  for  this  purpose 
could  contain  all  the  necessary  code,  or  open  other  Amiga  libraries  to 
perform  functions.  Or  you  could  write  a  library  that  works  closely  with  a 
specific  application  program,  enabling  certain  program  operations  to 
avoid  reference  to  commands  and  work  only  with  functions.  This  has  its 
advantages,  because  the  application  program  doesn't  have  to  interpret 
commands  or  receive  and  answer  messages.  A  library  can  contain  more 
than  entry  points  for  entire  and  specific  operations;  it  can  contain  code 
that  is  used  directly  by  the  application  program. 

As  indicated,  function  libraries  can  act  as  bridges  to  other  system  libraries 
or  application  libraries.  If  an  ARexx  program  controls  "Intuition",  a 
corresponding  function  library  could  recognize  appropriate  function 
names,  calculate  the  needed  offset,  if  necessary,  convert  individual 
parameters,  and  then  call  the  corresponding  function  in  the 
intuition.library.  Also,  ARexx  can  be  applied  as  a  test  platform  for  new 
functions;  it's  easier  to  manage  than  a  C  program,  which  must  be  re- 
compiled after  each  change  and  offers  no  tracing  functions. 

Whatever  the  task,  function  libraries  all  have  the  same  structure.  They 
contain  a  portion  of  the  normal  EXEC  system  library  with  the  basic 
functions  OPEN,  CLOSE  and  EXPUNGE  as  well  as  a  reserved  vector. 
There  must  also  be  a  QUERY  function  that  can  compare  the  name 
delivered  by  ARexx  with  the  names  of  the  functions  it  contains  and  then 
call  the  correct  one.  Normally  this  is  the  first  function  after  the  system 
functions  and  has  an  offset  of  -30.  Function  libraries  should  be  fully  re- 
enterable, since  many  ARexx  programs  can  run  simultaneously  and  use 
the  same  functions.  If  this  is  not  possible  because  of  other  constraints,  the 
query  function  must  contain  a  mechanism  that  prevents  the  function 
from  being  called  more  than  once. 
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Function  calls 

The  QUERY  function  is  accessed  by  the  interpreter  with  the  address  of  a 
message  in  AO  and  a  LIBRARYBASE  in  A6.  The  message  has  the  same 
structure  as  all  Rexx  messages,  and  is  not  passed  by  a  message  port  yet. 
In  ARGO,  a  pointer  indicates  the  function  name  it's  searching  for  in  the 
table.  If  this  name  is  not  found,  an  error  code  of  1  ("program  not  found") 
must  be  returned  in  DO.  The  library  is  then  closed  and  the  search 
continues.  The  message  itself  should  not  be  changed,  since  it  must  be 
passed  from  one  library  to  the  next  until  the  function  is  found. 

Parameter  conversion 

If  the  called  function  is  found,  sometimes  the  hierarchically  higher 
parameters  must  be  converted  to  the  form  the  function  is  expecting. 
Depending  on  the  structure  of  the  functions,  it  could  be  enough  to  move 
the  pointer;  but  sometimes  parameters  or  pointers  must  be  supplied  in 
specific  registers.  Arguments  are  always  passed  as  ARG  strings  that  can 
be  treated  as  normal  strings  supplied  with  O's.  Other  attributes  of  strings 
have  a  negative  pointer  offset  that  can  be  useful. 

Numeric  values  are  passed  as  strings  of  ASCII  symbols  and  must  be 
converted  into  integers  or  variable  decimal  format  in  order  to  perform 
arithmetic  calculations.  The  ARexx  system  library  contains  several 
functions  that  are  useful  for  these  purposes. 

The  number  of  arguments  can  be  determined  with  the  lowest  value  bytes 
of  the  action  code.  The  function  name  in  ARGO  is  not  counted  here,  but 
it's  counted  for  arguments  that  are  set  to  zero  and  are  used  as  default 
values. 

The  parameter  block  of  the  message  (with  ARGO  to  ARG  15)  is  structured 
just  like  the  argument  array  (argcargv)  function  of  a  C  program.  This 
makes  it  easy  to  incorporate  a  C  program  into  a  function  library:  the 
query  function  simply  calculates  the  address  of  the  function  you  want, 
the  address  of  the  parameter  block  and  the  number  of  arguments  that 
must  be  placed  on  the  program  stack  before  the  function  is  started. 
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Returned  values 

Each  function  in  a  library  must  return  an  error  code  and  a  result  string. 
The  error  code  must  be  located  in  DO;  if  it's  0,  Al  must  contain  an  ARG 
string  pointer.  The  routine  that  creates  the  correct  returned  values  can  be 
part  of  the  query  function,  so  that  all  functions  return  via  this  path. 
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10,  The  ARexx  Interface 


Using  ARexx,  there  are  two  methods  of  communication  with 
independent  external  programs: 

The  command  interface 

With  message  system  commands,  sent  to  the  address  of  an  initialized 
message  port  corresponding  to  an  application  program,  from  which 
answering  messages  are  in  turn  expected. 

The  external  function  environment 

Messages  are  exchanged  with  another  task;  a  call  to  a  function  name  still 
follows,  accessed  from  a  specified  library  list  and  function  environments. 
Both  argument  and  returned  values  must  conform  to  ARexx 
conventions. 

The  Rexx  master  procedure  is  the  common  communications  carrier  for 
ARexx  and  external  applications.  It  opens  the  public  message  port 
"REXX"  and  handles  many  administrative  tasks,  and  also  acts  as  a  "host". 
As  a  host,  it  starts  ARexx  programs  and  manages  global  resources.  The 
task  structures  of  all  running  ARexx  programs  are  maintained  in  a  list,  the 
contents  of  this  list  is  available  to  external  programs. 

The  interpreter  is  located  in  an  operating  system  library  and  offers  many 
entry  points  that  are  useful  for  the  implementation  of  ARexx  interfaces  in 
other  programs.  It  contains  functions  that  are  able  to  create  ARexx 
structures,  such  as  a  RexxMessage  or  arg  string,  to  manipulate  and  delete 
them.  These  functions  should  always  be  used,  since  future  expansions 
can  cause  problems.  Available  functions  are  documented  in  more  detail 
later. 
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10.1    Essential  Data  Structures 


In  most  applications,  the  programmer  uses  two  structures  with  ARexx. 
The  ARexx  "arg  structure"  is  used  for  all  strings  handled  by  the 
interpreter.  Normally,  they  are  passed  as  arg  strings,  with  pointers  that 
indicate  the  string.  The  Rexx  "msg  structure"  is  used  for  all 
communication  with  external  programs  and  is  structurally  an  expansion 
of  the  EXEC  message  form. 

Arg  strings:  all  strings  in  ARexx  are  stored  as  Rexx  arg  structures, 
created  for  each  string  in  an  equivalent  length.  Strings  are  passed  as  arg 
strings  (i.e.,  a  pointer  to  the  area  where  data  is  located  in  the  Rexx  arg 
structure).  The  data  always  ends  with  a  zero  in  order  to  allow  treatment 
as  normal  C  strings  in  other  programs.  Additional  data  such  as  length, 
hash  value  etc.  can  then  be  accessed  with  negative  offset  of  the  arg 
string  pointer. 


struct  RexxArg  { 
LONG  ra_Size; 
UWORD  ra_Length; 
UBYTE  ra_Flags; 
UBYTE  ra_Hash; 
BYTE  ra_Buff [8] ; 
} 


/*  reserved  total  length  of  the  structure  */ 

/*  length  of  the  string  */ 

/*  attribute  of  a  string  */ 

/*  hash  value  */ 

/*  data  area  (where  the  arg  string  points)  */ 

/*  minimum  size:  16  bytes*/ 


There  are  library  functions  used  to  create  arg  strings  (CreateArgstringO) 
and  to  delete  them  (DeleteArgstringO),  as  well  as  converting  from  whole 
numbers  into  this  format. 

Message  Packets 

All  communication  between  ARexx  and  external  programs  takes  place 
with  RexxMsg  structures.  There  is  a  function  in  the  ARexx  system 
library  that  lets  you  create  them  (CreateRexxMsgO)  and  one  to  delete 
them  (DeleteRexxMsgO). 

Messages  sent  by  ARexx,  for  example,  to  pass  a  command  to  an 
application  program,  have  the  same  form  as  those  that  move  in  another 
direction  to  start  a  macro  program.  You  can  distinguish  one  from  the 
other  because  all  messages  that  are  sent  by  ARexx  contain  a  pointer  to 
the  string  "REXX"  in  the  name  slot  of  the  node.  This  can  be  useful  in 
distinguishing  messages  when  a  port  receives  them  from  several  sources. 
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struct  RexxMsg  { 

STRUCT  Message  rra_Node;  /* 

APTR  rm_TaskBlock;  /* 

APTR  rm_LibBase;  /* 

LONG  rm_Action;  /* 

LONG  rm_Resultl;  /* 

LONG  rm_Result2;  /* 

STRPTR  rm_Args [16];  / * 

/* 
STRUCT  MsgPort  *rm_PassPort ; /* 

STRPTR  rm_CommAddr ;  /* 

STRPTR  rm_FileExt;  /* 

LONG  rm_Stdin;  /* 

LONG  rm_Stdout;  /* 

LONG  rm_avail;  /* 

}  /* 


and  EXEC  message  structure  */ 

pointer  to  the  sender's  task  structure  */ 

pointer  to  RexxSysBase  */ 

action  codes  */ 

primary  result  (Returncode)  */ 

secondary  result   */ 

pointers  to  arguments  0-15*/ 

the  expanded  area  */ 

pointer  to  the  next  port*/ 

name  of  its  own  port  */ 

file  name  extension  */ 

file  handle  of  the  input  data-flow*/ 

file  handle  of  the  output  data-flow  */ 

for  future  expansion  */ 

size:  128  bytes*/ 


Resource  Nodes 

A  further  useful  structure  is  often  used  by  ARexx  to  set  up  resource  lists: 
the  Rexx  "rsrc  structure".  It  has  a  variable  length,  that  is  entered  in  the 
structure,  along  with  the  address  of  the  function  used  to  remove  the 
structure.  This  means  that  heterogeneous  lists  can  be  set  free  by  calling 
RemRsrcList(). 
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10.2   Requirements  for  a  Command 
Interface 

An  application  program  that  wants  to  communicate  with  ARexx  only 
needs  a  public  message  port  and  a  program  input  that  can  process  the 
commands  received  there.  Usually  this  isn't  too  much  to  manage,  since 
many  programs  often  already  have  several  message  ports  receiving 
keyboard  and  menu  operations.  For  a  program  that's  directed  by 
commands,  it  processes  the  incoming  commands  easily  and  reacts 
accordingly.  With  menu-driven  programs,  more  work  is  necessary  once 
commands  do  more  than  just  activate  individual  menu  options.  Which 
commands  are  recognized,  and  the  syntactic  form  of  each,  depends  on 
the  programmer. 

An  application  program  sends  a  command  call  message  to  the  Rexx 
master  procedure,  usually  in  direct  response  to  user  entry.  As  soon  as  the 
report  is  received,  a  new  DOS  procedure  starts,  that  examines  the 
command  line,  takes  the  first  word,  and  searches  for  an  equivalent  macro 
program  file  (possibly  with  an  application-specific  extension  that  was 
passed  with  the  filename).  When  a  file  of  the  same  name  is  found,  the 
program  is  executed.  Usually  the  program  sends  back  one  or  more 
commands  to  the  public  port  of  the  calling  program.  While  one  is  being 
executed,  the  macro  program  waits  until  it  receives  a  return  code  from  the 
command.  If  an  error  is  encountered,  it  should  be  able  to  handle  it 
logically.  Finally,  the  macro  program  should  end  and  pass  the  command 
call  message  back  to  the  application  program  with  an  appropriate  return 
code. 

Error  trapping  in  macro  programs  is  an  important  feature  of 
communication.  Macro  programs  must  be  able  to  recognize  whether  a 
command  was  executed  correctly,  or  if  something  went  wrong  in  the 
process  in  order  to  react  intelligently  to  whatever  happens. 

Normally,  a  command  call  message  is  not  answered  if  the  error  status  that 
followed  the  command  is  known.  Programs  that  receive  commands  from 
a  message  port,  from  user  input  and  handle  both  with  the  same  routines, 
must  be  able  to  differentiate  between  the  two  input  modes.  A  flag 
indicates  what  happens  in  case  of  an  error.  In  the  first  case,  an 
appropriate  error  code  can  be  returned  and  in  the  second  case,  with 
direct  input,  an  error  message  should  also  display  on  the  screen. 
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Return  codes  that  appear  in  the  result  slot  of  the  message  should  also 
report  the  severity  of  the  error.  Small  whole  numbers  would  indicate 
relatively  harmless  errors,  and  large  numbers  would  appear  with  major 
errors.  This  enables  a  programmer  to  set  a  "failure  level"  in  order  to  ignore 
small  errors  and  report  those  that  exceed  it.  Other  than  this  convention,  a 
programmer  has  free  choice  of  error  codes. 

Every  program  meant  to  support  the  command  interface  must  open  a 
public  message  port.  If  a  command  is  to  be  sent  to  the  program,  it  receives 
a  Rexx  message  with  the  rm_Action  entry  "RXCOMM"  and  an  arg  string 
pointer  to  the  command  line  in  ARGO,  at  this  port.  The  other  ARG  entries 
are  not  used  with  commands.  There  are  two  pointer  entries  that  could  be 
interesting  for  the  program:  rm_TaskBlock  points  to  the  sender's  task 
structure  and  rmJLibBase  points  to  the  base  address  of  the  ARexx 
system  library.  With  the  exception  of  the  result  code  in  rm_Resultl  and 
possibly  also  rm_Result2,  the  program  should  not  change  the  message. 

These  appear  when  the  corresponding  command  has  been  completed. 
rm_Resultl  receives  an  error  code,  0  if  the  command  was  carried  out  with 
no  errors.  This  long  word  is  later  assigned  to  the  variable  RC  in  the  macro 
program. 

If  the  macro  program  expects  a  result  string  (indicated  with  the 
RXFB_RESULT  bit  in  the  command  code),  the  corresponding  arg  string 
pointer  in  rm_Result2  should  be  returned.  A  result  string  should  only  be 
returned  when  it's  requested  and  if  rm_Resultl  is  zero;  otherwise  a  zero 
must  be  entered  in  rm_Result2.  If  this  convention  is  not  followed,  a  loss 
of  memory  capacity  results.  An  unexpected  result  string  can  lead  to  a 
program  crash  if  memory  areas  become  free  without  being  assigned  (or  at 
least  not  with  an  arg  string). 

Many  application  programs  support  simultaneous  work  on  several  data 
files:  most  word  processors  let  users  open  windows  with  separate  files  in 
them.  If  an  ARexx  macro  program  is  called  by  the  editor,  it  must  be  clear 
to  which  file  the  returned  commands  apply. 

ARexx  supports  this  distinction  with  the  entry  rm_CommAddr,  in  which 
the  opening  ADDRESS  setting  for  a  (new)  macro  can  be  entered.  The 
word  processor  can  then  assign  a  separate  message  port  (for  example, 
"xyEditl",  "xyEdit2",  etc.)  for  each  file,  and  report  the  appropriate  name 
when  macro  calls  are  encountered. 
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Application  programs  can  open  several  ARexx  ports  that  can  also  be 
used  to  differentiate  command  classes,  each  of  which  is  then  sent  to  the 
correct  port  with  the  ADDRESS  command. 

ARexx  program  calls  are  made  by  sending  a  corresponding  report  to  the 
Rexx  master  procedure.  Programs  can  be  called  as  commands  or  as 
functions;  the  command  mode  is  generally  easier  and  more  free,  since 
only  a  few  fields  of  the  message  must  be  completed. 

When  an  ARexx  message  structure  is  created,  all  entries  are  first  set  to  0. 
Entries  that  are  filled  by  the  sending  program  are  never  changed  by 
ARexx  so  that  this  structure  can  be  re-used  after  the  initial  message  is 
answered.  For  this  reason,  only  one  structure  is  necessary,  which  must 
then  only  be  partially  changed  for  new  calls. 

In  the  rm_Action  slot  of  the  message,  the  mode  of  the  call  is  determined. 
For  command  mode,  RXCOMM  is  entered;  for  function  mode,  RXFUNC. 

In  addition,  certain  flags  can  be  set,  to  enable  options  that  are  described 
later. 

Command  strings,  function  names,  and  arguments  must  be  entered  as  arg 
strings.  Normal  strings  can  be  comfortably  created  with  the 
CreateArgstringO  function.  Returned  arg  strings  can  usually  be  treated 
as  normal  strings,  since  the  pointer  refers  to  the  data  area  (a  string  that 
ends  with  a  0).  Because  the  corresponding  strings  are  not  changed  in  the 
course  of  an  ARexx  program,  a  program  may  have  to  build  up  many  of 
these  structures.  The  pointer  that  is  returned  by  CreateArgstringO  is 
placed  in  the  equivalent  slot  of  the  message:  ARGO  for  the  command 
string  or  function  name,  ARG1  to  ARG15  for  function  arguments.  When 
the  message  is  answered,  extra  arg  strings  can  be  deleted  with 
Delete  Argstring(). 

When  all  the  necessary  fields  are  filled,  the  report  is  sent  to  the  public 
Port  "REXX"  using  the  EXEC  function,  PutMsg().  Its  address  must  first 
be  determined  with  the  function  FindPort(),  but  this  value  should  not  be 
saved  by  the  program  because  the  port  can  be  closed  at  any  time.  To 
ensure  against  program  crash,  you  must  bracket  the  calls  to  FindPort() 
and  PutMsgQ  with  Forbid()  and  Permit(). 
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After  sending  the  message,  the  application  program  can  resume  its  own 
tasks  and  the  macro  program  runs  as  a  separate  task.  It's  often  useful  to 
prevent  further  user  input  for  the  duration  of  the  ARexx  macro  so  that 
data  accessed  by  the  macro  is  not  changed  by  the  user. 


10.2.1         Command  Calls 


Command  mode  returns  a  command  string  to  the  calling  program.  The 
string  consists  of  a  macro  name,  an  empty  space  and  arguments  in 
whatever  form  necessary.  ARexx  takes  the  name,  usually  the  name  of  the 
executing  program,  and  tries  to  start  it.  Normally  the  rest  of  the  command 
string  is  a  single  argument  the  program  uses.  The  RXFB_TOKEN  flag  can 
adjust  behavior:  if  it's  set,  then  the  rest  of  the  string  is  parsed  into  several 
arguments.  In  this  process,  words  are  separated  as  they  would  be  with 
PARSE.  The  number  of  arguments  is  not  limited  in  this  case,  since  they 
don't  have  to  fit  into  the  15  available  message  slots.  In  order  to  prevent 
spaces  that  represent  arguments  from  being  divided,  they  can  be 
enclosed  in  quotation  marks  ["  "].  If  such  a  section  contains  quotation 
marks,  use  single  quotes;  the  two  types  of  quotation  symbols  can  be  used 
alternately.  Double  entry  of  one  of  the  symbols  doesn't  work  here.  At  the 
end  of  the  string,  no  quotation  mark  is  necessary. 


For  example,  the  call: 

test.rexx  "The  first  argument"  second  "'one  more' 

would  mean  that  the  command: 

parse  arg  A1,A2,A3;  say  Al;  say  A2;  say  A3 

would  output  as  follows: 

The  first  argument 

second 

' one  more ' 


If  the  first  element  of  a  command  string  is  already  in  quotation  marks,  it's 
assumed  not  to  be  a  program  name,  but  rather  as  a  single  word.  This  is  an 
easy  method  for  starting  very  short  ARexx  programs  (its  length  is  not 
limited  in  any  way).  If  RXFB_TOKEN  wasn't  specified,  only  the  first 
section  that  appears  in  quotation  marks  is  examined,  and  the  rest  is 
discarded.  The  rxfb_string  flag  defines  the  entire  command  string  as  an 
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ARexx  program  text.  In  this  case,  no  parsing  takes  place  and  the  program 
is  immediately  executed.  Calls  usually  don't  expect  a  result  string.  The 
flag  RXFB_RESULT  can  request  it.  The  calling  program  must  delete  the 
string,  which  is  hierarchically  higher  than  itself,  when  it's  no  longer 
necessary. 


10.2.2  Function  Calls 

Function  calls  pass  a  function  name  and  up  to  IS  arguments  as  strings  to 
the  application  program.  The  function  name  is  used  for  access.  The  actual 
number  of  arguments  (not  counting  the  name)  must  be  written  to  the 
lowest  value  byte  of  the  command  code. 

This  form  is  normally  used  when  a  result  is  expected  (but  this  does  not 
require  the  use  of  a  function  call)  or  when  several  argument  strings  are 
already  available.  A  result  is  again  requested  with  the  RXFB_RESULT 
flag.  After  the  function  is  completed,  if  no  error  took  place,  and  Resultl  is 
zero,  the  pointer  in  Result2  should  be  set  to  the  equivalent  string. 

10.2.3  ARexx  Program  Search  Order 

Again,  ARGO  can  contain  a  complete  program  instead  of  a  filename.  It's 
signaled  with  the  rxfb_string  flag. 

Searching  for  program  files  is  a  two-step  process,  in  which  the  current 
name  extension  (".rexx",  if  nothing  else  is  specified  in  the  message)  is 
attached  to  the  filename,  if  not  previously  specified.  If  the  search  is 
unsuccessful,  the  un-expanded  name  is  used  for  a  new  search. 

If  the  name  contains  a  path,  the  program  only  looks  there;  otherwise  the 
current  directory  is  searched  first  (possible  with  both  name  variations) 
and  then  the  REXX:  directory.  A  command  call  with  "RAM:t/examples" 
would  be  searched  for  in  RAM:t  under  the  names  "examples.rexx"  and 
then  "examples".  Without  the  path  name,  the  search  order  would  be 
"examples.rexx",  "examples",  "REXX:examples.rexx"  and 
"REXX:examples". 

If  a  program  is  still  not  found,  one  more  possibility  exists:  If  the  message 
path  rm_PassPort  was  filled  in,  the  message  is  simply  passed  to  the  port 
specified  there.  This  means  that  one  command  can  be  passed  to  several 
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programs,  until  one  of  them  can  do  something  with  it.  If  there  is  a  0  the 
message  is  answered  with  an  error  code  1  ("program  not  found"). 

10.2.4        Expanded  RexxMsg  Structure  Areas 

Entries  in  this  area  of  the  message  can  adjust  various  default  settings.  If 
no  settings  are  being  changed,  these  can  be  left  at  zero. 

Application  programs  should  enter  values  for  the  appropriate  name 
extension  and  the  name  of  their  own  ports.  The  name  extension  is  useful 
to  identify  macro  programs  for  specific  applications  from  other  program 
files  and  should  be  specific  to  each  program.  Entering  the  port  for  the 
program  is  done  so  the  addressed  port  is  already  set  at  the  beginning  of 
the  macro.  Since  one  program  can  have  several  ports  and  the  macro  must 
know  where  it  should  direct  its  commands,  this  is  very  important.  Use  the 
application  program  name  or  an  abbreviation  of  it. 

PassPort 

In  the  rm_PassPort  slot,  a  further  message  port  address  can  be  entered. 
The  report  is  sent  to  this  port  if  no  corresponding  program  file  is  found. 
This  port  should  be  a  secured  resource  so  that  it  cannot  be  removed  until 
the  message  has  been  passed.  It  does  not  have  to  be  a  public  port;  for 
this  reason  it's  not  possible  to  make  sure  it's  available  before  the  message 
is  passed  on. 

Host  address 

An  entry  in  the  rm_CommAddr  slot  can  indicate  the  ADDRESS  setting 
for  an  ARexx  program  that  is  to  be  started.  The  entry  includes  a  pointer 
to  a  string  that  closes  with  a  zero  and  contains  the  name  of  the  public 
message  port  to  which  commands  are  to  be  directed.  This  option  is  very 
important  for  application  programs  that  allow  work  on  several  files 
simultaneously  and  open  a  separate  message  port  for  each  file.  The  name 
of  the  correct  ports  are  then  passed  to  a  macro  when  it's  called.  If  such  an 
entry  is  not  found,  "REXX"  is  the  default  setting. 
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File  Extension 

The  entry  for  rm_FileExt  changes  the  default  value  of  ".rexx"  for  file 
name  extensions.  Application  programs  should  enter  a  specific  extension 
here,  common  to  all  its  macro  programs.  If  it  is  a  pointer  to  a  string  it  is 
terminated  with  a  zero. 

Input  and  output  data  flow 

Default  values  for  data  input  and  output  of  an  ARexx  program  are 
directly  taken  from  the  procedure  structure  of  the  calling  application 
program,  as  it's  a  DOS  procedure.  One  or  both  data  streams  can  be 
diverted  by  entering  corresponding  DOS  file  handles  in  the  rm_Stdin  and 
rm_Stdout  slots.  The  data  flow  cannot  be  closed  as  long  as  the  program 
is  running.  Both  values  are  entered  directly  in  the  procedure  structure  of 
the  calling  program. 

The  output  stream  is  simultaneously  the  pre-set  target  for  trace  output  by 
the  program.  If  interactive  tracing  is  used,  the  output  stream  should 
always  be  defined  to  an  interactive  device  like  CON:,  since  user  entry  is 
also  expected. 

If  an  ARexx  program  is  called  by  an  EXEC  task,  these  entries  are  the 
only  way  to  control  input  and  output. 


10.2.5        Result  Entries 


A  message  that  is  started  by  an  ARexx  program  is  answered  as  soon  as 
it's  completed.  Two  result  entries  then  contain  either  error  codes  or  a 
possible  result  string. 

If  the  primary  result  in  rm_Resultl  is  zero,  the  program  ran  without  errors 
and  the  pointer  in  rm_Result2  indicates  a  result  string,  if  requested.  If  the 
primary  result  is  not  zero,  two  things  may  have  happened:  either  the 
secondary  result  is  zero,  meaning  that  the  return  code  was  passed  with 
"EXIT  re",  or  it's  "RETURN  re".  This  can  be  an  error  code  or  a  result;  how 
this  return  code  is  handled  depends  on  the  calling  program.  If  the 
secondary  result  is  not  zero,  then  the  primary  result  is  an  error  level 
indicating  the  severity  of  the  error  and  Result2  is  an  ARexx  error  code. 
This  should  be  reported  to  the  user.  In  order  to  translate  the  error  code  to 
an  equivalent  text,  the  function  ErrorMsgO  is  provided. 
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Result  strings  are  the  responsibility  of  the  calling  program  and  must  be 
deleted  with  the  DeleteArgstringO  function  when  they  are  no  longer 
needed. 
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10.3  The  Rexx  Master  Procedure 

All  communication  with  the  Rexx  master  procedure  takes  place  using  the 
message  structure  previously  described.  It  contains  a  command  entry  that 
indicates  which  operation  is  to  be  carried  out  and  entries  for  the 
appropriate  or  necessary  parameters.  Messages  received  are  immediately 
handled,  either  being  answered  or,  in  the  case  of  program  calls,  passed 
on.  The  structure  contains  two  result  entries  with  which  error  codes  or 
result  strings  are  transmitted.  In  the  parameter  portion  of  the  structure, 
either  whole  numbers  of  the  "long"  type  or  pointers  to  arg  strings  can  be 
entered. 


10.3.1        Action  Codes 


Valid  command  codes  are  described  here.  The  commands  are  listed  in 
order  of  their  mnemonics,  followed  by  the  permitted  flags.  The  resulting 
code  is  formed  by  a  logical  OR  of  the  action  code  and  all  necessary  flags. 
This  code  is  entered  in  the  rm_Action  slot. 

IRXADDCON  [RXFB  NONRET]  | 

Adds  an  entry  to  the  cliplist.  ARGO  points  to  the  name,  ARG1  points  to 
the  data  and  ARG2  contains  the  length  of  the  data.  This  is  not  required 
to  be  an  arg  string.  The  name  should  be  a  string  that  closes  with  a  2ero, 
but  the  data  itself  can  contain  null  bytes;  its  length  is  explicitly  indicated. 

IRXADDFH  [RXFB  NONRET]  | 

Adds  a  function  environment  to  the  library  list.  The  first  argument,  ARGO, 
points  to  a  name  string  closed  with  a  zero  along  with  a  port.  The 
argument  ARG1  contains  the  search  priority.  A  priority  can  be  specified 
as  an  integer  ranging  from  -100  to  100.  If  a  previous  entry  of  the  same 
value  exists,  the  message  is  returned  with  a  warning  and  the  appropriate 
error  code.  No  check  is  made  to  verify  existence  of  the  port. 
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IRXADDLIB  [RXFB  NONRET]  1 

Adds  an  entry  to  the  library  list.  The  argument  ARGO  points  to  a  name 
string  that  ends  with  a  zero,  with  the  name  of  the  function  library  or  of 
the  function  environment  port.  The  search  priority  is  set  with  ARG1,  a 
whole  number  between  -100  and  100;  the  remaining  area  is  reserved  for 
later  expansion.  The  offset  for  the  "query"  function,  specified  in  ARG2 
and  ARG3,  contains  the  version  number.  If  a  previous  entry  of  the  same 
name  exists,  the  message  is  returned  with  a  warning  and  the  error  code. 
Otherwise,  the  new  entry  is  accepted  and  the  library  or  function 
environment  is  available  to  ARexx  programs.  There  is  no  check  for  actual 
availability  of  the  library,  nor  whether  it  can  be  opened. 


RXCOMM  [RXFBTOKEN]  [RXFBSTRING]  [RXFBRESULT] 
[RXFB  NOIO] 


Calls  an  ARexx  program  in  command  mode.  ARGO  must  contain  an  arg 
string  pointer  to  the  command  string.  The  flag  RXFB_TOKEN  specifies 
how  the  command  string  is  to  be  parsed  into  several  arguments.  Or 
RXFB_STRING  indicates  that  the  command  string  itself  contains  the 
program.  This  call  usually  does  not  deliver  a  result  string; 
RXFB_RESULT  can  be  used  to  request  one,  but  the  calling  program 
must  then  make  sure  this  string  is  deleted  after  use.  The  argument 
RXFB_NOIO  prevents  the  input  and  output  of  the  called  program  from 
being  used  by  the  caller. 


RXFUNC  [RXFB_RESULT]  [RXFB_STRING]  [RXFB_NOIO] 
Number  args 


Calls  to  a  function.  A  pointer  in  ARGO  refers  to  the  function  name.  ARG1 
to  ARG  15  point  to  arguments.  All  of  them  must  be  arg  strings.  The  lowest 
value  byte  of  the  action  code  is  the  number  of  arguments  (not  counting 
the  function  name).  For  function  calls,  RXFB_RESULT  is  used  to  request 
a  result  string,  but  this  is  not  required.  RXFB_STRING  shows  whether 
the  entire  command  string  contains  the  program.  Finally,  RXFB_NOIO 
prevents  the  input  and  output  of  the  called  program  from  being  used  by 
the  caller. 
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|RXREMCON[RXFB  NONRET] 


Removes  an  entry  from  the  cliplist.  ARGO  is  a  string  that  closes  with  a 
zero  and  points  to  the  name  to  be  removed.  The  cliplist  is  searched  for  an 
entry  with  the  desired  name.  If  it's  found,  the  entry  is  removed  from  the 
list  and  the  storage  area  it  occupied  is  released.  If  the  name  is  not  found, 
the  message  is  returned  with  an  error  code. 


IRXREMLIB  [RXFB  NONRET] 


Removes  an  entry  from  the  library  list.  ARGO  is  a  string  that  closes  with  a 
zero  and  points  to  the  name  to  be  removed.  The  library  list  is  searched  for 
an  entry  with  the  desired  name,  whether  it's  a  function  environment  or  a 
system  library.  If  it's  found,  the  entry  is  removed  from  the  list  and  the 
storage  area  it  occupied  is  released.  If  the  name  is  not  found,  the  message 
is  returned  with  an  error  code.  The  entry  is  not  removed  if  an  ARexx 
program  is  in  the  process  of  calling  it. 

1RXTCCLS  [RXFB  NONRET]  | 

Closes  the  global  Trace  window.  If  no  ARexx  program  is  waiting  for 
entry  from  the  Trace  window,  it's  immediately  closed;  otherwise  the 
program  waits  until  the  active  programs  are  no  longer  using  it. 

IRXTCOPN  [RXFB  NONRET]  | 

Opens  the  global  Trace  window.  After  this  instruction,  the  Trace  output 
from  all  active  ARexx  programs  is  redirected  to  the  Trace  window.  User 
entry,  for  interactive  tracing,  is  also  expected  there.  There  can  only  be 
one  open  Trace  window  at  a  time;  if  it's  already  open,  the  message  is 
returned  with  a  warning. 


10.3.2        Action  Code  Control  Flags 


In  addition  to  the  command  codes,  individual  bits  can  be  inserted  in  the 
action  code  to  activate  special  functions.  In  the  individual  commands, 
only  certain  flags  are  accepted,  all  others  are  ignored. 

RXFB_NOIO  With  the  command  code  RXCOMM  or  RXFUNC,  this 
flag  prevents  automatic  transfer  of  input  and  output 
data  to  the  calling  program. 
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RXFB_NONRET 

Determines  that  the  recipient  will  not  respond  to  the 
report.  This  also  means  that  it  doesn't  matter  to  the 
sender  whether  or  not  the  operation  was  successful, 
since  there  is  no  other  way  to  inform  it  about  success  or 
failure.  The  message  is  transferred  of  the  receiver  and 
must  be  released  by  it  with  DeleteRexxMsg(). 

RXFB_RESULT 

With  RXCOMM  or  RXFUNC,  this  flag  controls  the 
transfer  of  a  result  string.  If  the  program  or  the  function 
ends  with  EXIT  (or  RETURN)  and  passes  on  an 
expression,  the  calling  program  receives  this  expression 
as  an  arg  string.  If  this  result  is  no  longer  needed,  the 
calling  program  must  remove  it  with  DeleteArgstringQ. 


RXFB  STRING 


With  RXCOMM  or  RXFUNC,  this  flag  indicates  that 
ARGO  does  not  contain  a  filename,  but  that  a  complete 
ARexx  program  was  passed  (which  then  does  not  have 
to  be  within  a  set  of  quotation  marks). 


RXFB  TOKEN 


Demands,  in  connection  with  the  command  code 
RXCOMM,  that  the  data  following  the  program  name 
not  be  passed  as  a  complete  argument,  but  instead 
parsed  into  words  and  transformed  into  several 
arguments.  Areas  enclosed  in  quotation  marks  are  not 
parsed,  so  that  spaces  are  possible.  At  the  end  of  the 
command  strings,  no  additional  quotation  marks  are 
necessary. 


10.3.3        Managing  the  Results 


The  Rexx  master  procedure  conforms  to  Amiga  code  conventions  for  the 
result  that's  passed  in  rm_Resultl .  This  is  an  error  level  set  for  "warning" 
at  5  (WARN)  and,  for  more  serious  errors,  reads  as  10  (ERROR)  or  20 
(FAIL).  The  value  in  rm_Result2  is  then  either  zero  or  an  ARexx  error 
number,  if  an  appropriate  one  is  available. 
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10.4   Functions  in  rexxsyslib. library 

The  ARexx  interpreter  is  part  of  the  Amiga  operating  system  library 
"rexxsyslib.library".  Many  of  the  functions  in  it  are  only  used  by  the 
interpreter  and  are  not  documented.  Others  can  be  of  use  to  other 
programs  that  use  ARexx. 

System  library  functions  are  meant  to  be  called  from  assembly  language 
programs  and  generally  only  affect  registers  A0  and  Al,  as  well  as  DO 
and  Dl.  Many  functions  return  values  in  several  registers  in  order  to 
reduce  code.  In  addition,  the  functions  control  the  status  register  CCR,  if 
appropriate.  Usually  CCR  refers  to  the  value  returned  in  DO. 

The  function  offsets  are  defined  in  the  file  rexx/rxslib.i,  included  after 
Kickstart  2.0  and  should  be  linked  in  matching  assembler  source  code.  It 
can  also  be  called  from  C  programs,  if  appropriate  code  is  included  in  the 
link. 

Overview  of  available  functions 

IIO  Functions 

There  are  two  groups  of  I/O  functions:  the  low  level  uses  DOS  file 
handles  directly,  while  the  higher  level  works  with  lists  of  I/O  buffer 
structures  and  supports  logical  filenames. 


CloseFO 

close  file  buffer 

CreateDOSPktO 

create  a  DOS  standard  packet  structure  and 

initialize  it 

DeleteDOSPkt() 

delete  a  DOS  standard  packet  structure 

DOSRead() 

read  from  a  DOS  file 

DOSWrite() 

write  to  a  DOS  file 

ExistF() 

test  whether  a  file  exists 

FindDevice() 

test  whether  a  DOS  device  exists 

OpenF() 

open  a  file  buffer 

QueueF() 

queue  a  line  in  a  file  buffer 

ReadF() 

read  a  character  from  a  file  buffer 

ReadStr() 

read  a  string  from  a  file  buffer 

SeekF() 

moves  the  access  pointer  to  a  specific  position 

StackF() 

adds  a  line  to  the  file  buffer 

WriteFO 

writes  characters  to  a  file  buffer 
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String  Manipulation 

ARexx  treats  all  data  as  strings.  These  functions  perform  common  string 
operations. 


CmpStringO 

compare  string  structures 

LengthArgstringO 

calculate  the  length  of  an  argument  string 

StcToken() 

select  a  token 

StrcmpN() 

compare  strings 

StrcpyA() 

copy  a  string  and  convert  to  ASCII 

StrcpyN() 

copy  a  string 

StrcpyU() 

copy  a  string,  converted  to  capital  letters 

StrflipN() 

transpose  a  string 

StrlenO 

determine  the  length  of  a  string 

Conversions 


CVa2i() 

convert  ASCII  to  INT 

CVc2x() 

convert  CHAR  to  HEX  or  BIN 

CVi2a() 

convert  INT  to  ASCII 

CVi2arg() 

convert  INT  to  an  ASCII  arg  string 

CVi2az() 

convert  INT  to  ASCII  with  leading  zeros 

CVs2i() 

convert  string  structure  to  INT 

CVx2c() 

convert  HEX  or  BIN  to  CHAR 

ErrorMsgO 

calculate  error  number  from  an  error  message 

ToUpperQ 

convert  ASCII  to  capital  letters 

ARexx  Resource  Handling 


AddClipNodeO 

assign  a  clip  node 

AddRsrcNode() 

assign  a  resource  node 

ClearMemO 

delete  a  storage  area 

ClearRexxMsgO 

delete  arg  strings  from  a  message 

ClosePublicPortO 

release  a  port  resource  node 

Create  ArgStringO 

create  an  arg  string  structure 

CreateRexxMessage() 

create  an  ARexx  message  structure 

CurrentEnv() 

determine  pointer  position  in  the  current 

storage  environment 

Delete  ArgstringO 

release  an  arg  string  structure 

DeleteRexxMsg() 

release  an  ARexx  message  structure 

FillRexxMsgO 

fill  arg  strings  in  a  Rexx  message 

FindRsrcNode() 

find  a  resource  node 

FreePort() 

close  a  message  port 

FreeSpaceO 

release  internal  storage 

GetSpaceO 

reserve  internal  storage 

InitListQ 

initialize  a  list  header  structure 
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10.4.1 


InitPortO 

IsRexxMsgO 

LengthArgstringO 

ListNames() 

LockRexxBase() 

initialize  a  message  port 

check  a  message 

calculate  the  length  of  an  arg  string 

list  node  names  in  an  arg  string 

protect  a  global  resource  from  data  write 

calls 

OpenPublicPortO 

RemClipNode() 

RemRsrcListO 

RemRsrcNodeO 

UnlockRexxBase() 

create  a  port  resource  node 
release  a  clip  node 
release  a  resource  list 
remove  a  resource  node 
release  a  resource 

I/O  Functions 


ICloseFQ 


Closes  file  buffer! 


Syntax: 


success  =  CloseFdoBuf  f ) 
DO  AO 


Releases  the  IoBuff  structure  and  closes  the  matching 
DOS  file.  An  entire  list  of  IoBuff  structures  can  be 
deleted  with  a  single  call  to  RemRsrcListO;  each 
individual  structure  is  then  processed  with  an  automatic 
CloseF(). 


CreateDOSPkt  0 


Creates  and  initializes  a  DOS  standard 
packet  structure 


Syntax: 


See  also: 


packet  =  CreateDOSPkt ( ) 
DO  AO 

(CCR) 

Reserves  a  storage  area  for  a  DOS  standard  packet 
structure  and  initializes  it  by  linking  it  to  the  EXEC 
message  and  DOS  packet  sub-structures.  A  ReplyPort  is 
not  automatically  added,  since  entries  are  normally  filled 
in  immediately  before  sending  the  message. 

DeleteDOSPktO 


604 


10.4  Functions  in  rexxsyslib.library 


IDeleteDOSPktQ 

Syntax: 


Releases  a  DOS  standard  packet  structure] 


DeleteDOSPkt (message) 
AO 

Releases  a  DOS  standard  packet  structure,  that  has 
normally  been  created  earlier  with  a  call  to 
CreateDOSPkt(). 


See  also: 


|  DOS  Read  () 


CreateDOSPktQ 


Reads  from  a  DOS  file  | 


Syntax:  count  =  DOSRead( filehandle, buffer, length) 

DO  AO  Al  DO 

(CCR) 

Reads  characters  from  the  DOS  "filehandle"  into  the 
"buffer".  "Length"  is  the  maximum  number  of  characters 
to  be  read,  "count"  returns  the  actual  number  of 
characters  read  after  the  call,  or  -1,  if  an  error  was 

encountered. 


IDOSWriteQ" 


Writes  to  a  DOS  file  | 


Syntax:  count  =  DOSWrite (filehandle, buffer, length) 

DO  AO  Al  DO 

(CCR) 

Writes  characters  from  "buffer"  to  the  given  DOS 
filehandle.  "Length"  is  the  maximum  number  of 
characters  to  be  written,  "count"  returns  the  number  of 
characters  actually  written,  or  -1  if  an  error  was 
encountered. 


|ExistF() 


Tests  whether  a  file  exists  I 


Syntax: 


success  =  ExistF (filename) 
DO  AO 

(CCR) 
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IFindDeviceQ 


Verifies  whether  a  file  exists  by  trying  to  receive  a 
Read-Lock  for  the  file.  The  result  determines  whether 
the  operation  was  successful  and  the  lock  is  released. 

Tests  whether  a  DOS  device  exists  | 


Syntax: 


device 

=  FindDevice (devicename, type) 

DO 

AO        DO 

AO 

(CCR) 

IQpenFQ 


Searches  in  the  DOS  DeviceList  for  a  device  node  of 
equivalent  type,  whose  name  equals  "devicename". 
Available  "types"  are  the  constants  DLT_DEVICE, 
DLT_DIRECTORY  or  DLT.VOLUME,  that  are  defined 
in  DOS  includes.  The  name  is  converted  to  capital  letters 
before  the  comparison.  The  argument  "device"  is  a 
pointer  to  the  device  node,  or  0  if  nothing  was  found. 

Opens  a  file  buffer] 


Syntax: 


IoBuff  =  OpenF (list, filename, mode /logical) 
DO  AO      Al      DO     Dl 

AO 

(CCR) 


See  also: 


Attempts  to  open  a  DOS  file.  The  parameter  "mode"  is 
one  of  the  constants  RXIO_READ,  RXIO_WRITE  or 
RXIO_APPEND,  that  are  defined  in  ARexx  Includes.  If 
it's  successful,  an  IoBuff  structure  is  created  and  added 
to  the  "list".  The  "list"  must  be  a  pointer  to  a  regular 
EXEC  list  header.  The  argument  "logical"  is  a  pointer  to 
the  logical  filename,  or  0  if  such  a  value  is  not  needed. 

CloseFQ 
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IQueueFQ 


Syntax: 


See  also: 


Adds  a  line  to  a  file  buffer  I 


count  =  QueueFdOBuff ,  buffer,  length) 
DO  AO        Al     DO 

Adds  a  line  to  a  data  stream  that  belongs  to  the  given 
IoBuff  structure.  This  data  stream  must  be  directed  by  a 
driver  that  recognizes  the  ACTION_QUEUE  command. 
The  parameter  "buffer"  is  a  pointer  to  the  data  to  be 
added  and  "length"  indicates  the  number  of  bytes  to  be 
added.  The  "count"  indicates  how  many  characters 
were  actually  transferred,  or  shows  -1  if  an  error  was 
encountered. 

StackFQ 


Reads  characters  from  a  file  buffer  | 


IReadFQ 


Syntax:  count  =  ReadFdoBuff ,  buffer,  length) 

DO  AO      Al      DO 

(CCR) 

Reads  characters  from  a  file  that  belongs  to  the  IoBuff 
structure.  The  value  in  "buffer"  is  a  pointer  to  the  target 
for  the  data  to  be  read  and  "length"  indicates  the 
number  of  characters  to  be  read.  The  "count"  reports 
how  many  characters  were  actually  transferred. 


IReadStrQ 


Reads  a  string  from  a  file  buffer] 


Syntax: 


(count, pointer)  =  ReadStr (IoBuff .buffer, length) 
DO     Al  AO     Al      DO 

Reads  characters  from  a  file  that  belongs  to  the  IoBuff 
structure  until  a  line-feed  (ASCII  10)  occurs.  The  line- 
feed characters  are  discarded.  "Buffer"  is  a  pointer  to 
the  target  of  the  data  read  and  "length"  is  the  maximum 
number  of  data  to  be  read.  The  "count"  relays  how 
many  characters  are  actually  taken,  or  -1  if  an  error  was 
encountered. 
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ISeekFQ 


Syntax: 


IStackFQ 


IWriteFQ 


Moves  the  access  pointer  to  a  specific  location  | 


position  =  SeekF(IoBuff , offset, anchor) 
DO  AO       DO     DO 

Moves  the  access  pointer  to  a  specific  location, 
indicated  by  "offset",  a  relative  byte  position,  given  in 
reference  to  the  "anchor"  point.  It  can  be  set  using 
"anchor"  to  the  beginning  (-1),  the  current  position  (0) 
or  to  the  end  of  the  file  (1).  The  "position"  returned  is 
the  new  position  in  reference  to  the  beginning  of  the 
file. 


Adds  a  line  to  the  file  buffer  | 


Syntax:  count  =  StackF( IoBuff, buffer, length) 

DO  AO       Al      DO 

Adds  a  line  to  the  data  stream  belonging  to  the  given 
IoBuff  structure.  This  data  stream  must  be  controlled  by 
a  driver  that  can  process  an  ACTION_STACK 
command.  The  "buffer"  points  to  the  data  location,  and 
"length"  is  the  number  of  bytes  to  be  added.  "Count" 
reports  how  many  characters  were  actually  transferred 
or  appears  as  -1  if  an  error  was  encountered. 


Writes  characters  into  a  file  buffer  | 


Syntax:  count  =  WriteFdoBuff , buffer,  length) 

DO  AO  Al  DO 

(CCR) 

Writes  characters  to  the  file  that  belongs  to  the  IoBuff 
structure.  "Buffer"  is  a  pointer  to  the  source  for  the  data 
to  be  written  and  "length"  is  the  number  of  data.  The 
"count"  indicates  how  many  characters  were  actually 
transferred  or  reads  as  -1  in  the  case  of  an  error. 
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10.4.2        String  Manipulation 


ARexx  treats  all  data  as  strings.  These  functions  fulfill  the  more  common 
string  operations. 


ICmpStringQ" 


Compares  string  structures! 


Syntax: 


test  =  CmpString(ssl,ss2) 
DO  AO  Al 

(CCR) 

Compares  two  ARexx  string  structures  whose  pointers 
form  the  arguments.  The  structures  also  contain  the 
length  and  hash  value  of  the  strings;  if  there  is  no 
agreement  in  these,  the  comparison  ends.  The  function 
returns  -1  (TRUE)  if  they  agree  or  otherwise  a  0 
(FALSE). 


lengthargstringO 


Calculates  the  length  of  an 
ARexx  arg  string 


Syntax: 


length  =  LengthArgstring(argptr) 

DO  AO 

Determines  the  length  of  the  argument  string  at  the 
given  address. 


IStcTokenQ" 


Pulls  out  one  token  | 


Syntax: 


(quote, length, scan, token)  =  StcToken( string) 
DO      Dl   AO    Al  AO 

Searches  a  string  for  the  next  token,  delimited  by  an 
empty  space,  and  returns  a  pointer  to  the  first  character 
of  this  token.  The  value  "quote"  contains  the  quotation 
mark  character  ("  or  ')  or  0;  spaces  found  within 
quotation  marks  are  not  located  with  this  function. 
"Length"  is  the  length  of  the  token  found,  including 
quotation  marks,  if  applicable.  "Scan"  is  a  pointer  to  the 
position  after  the  token  that  was  found,  which  prepares 
the  following  call. 
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IStrcmpNQ 


Syntax: 


IStrcpyAQ 


IStrcpyNQ 


Compares  strings  | 


test  =  StrcmpN(stringl,string2, length) 
DO  AO      Al      DO 

(CCR) 

The  strings  at  addresses  "  string  1"  and  "string2"  are 
compared  character  by  character,  until  "length"  is 
reached  or  a  deviation  is  recognized.  "Test"  is  -1  if  the 
first  string  was  shorter,  1  if  it  was  larger,  or  0  if  the  two 
strings  were  exactly  equal. 

Copies  a  string  and  converts  to  ASClT] 


Syntax:  hash  =     StrcpyA (destination, source, length) 

DO  AO  Al  DO 

Copies  the  string  at  the  location  "source"  to 
"destination".  In  the  process,  the  data's  MSB  is  deleted 
and  projected  onto  the  lower  128  characters  in  the 
ASCII  table.  The  string  can  contain  "00"x,  which  is  why 
"length"  is  necessary  (USHORT).  The  result  is  the  hash 
byte  of  the  copied  string. 


Copies  a  string  | 


Syntax:  hash  =  StrcpyN (destination, source, length) 

DO  AO         Al      DO 

Copies  the  string  found  at  "source"  to  "destination". 
The  string  can  contain  zeros  "00"x,  so  "length"  is 
necessary  (USHORT).  The  result  is  the  hash  byte  of  the 
copied  string. 
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|  StrcpyUQ  Copies  a  string  and  converts  to  capital  letters  | 

Syntax:  hash  =  StrcpyU (destination, source, length) 

DO  AO         Al     DO 

Copies  the  string  found  at  "source"  to  "destination". 
The  string  can  contain  zeros  "00"x,  so  "length"  is 
necessary  (USHORT).  The  result  is  the  hash  byte  of  the 
copied  string. 


IStrflipNQ 


Reverses  a  string  | 


Syntax:  StrflipN(string, length) 

AO  DO 

Transposes  the  order  of  characters  in  a  string  at  the 
given  storage  location. 


IStrlenQ 


Determines  the  length  of  a  string  | 


Syntax:  length  =  Strlen( string) 

DO  AO 

(CCR) 

Determines  the  number  the  characters  in  the  string 
(closed  with  "00"x  )  at  the  given  storage  location. 


10.4.3        Conversion  Functions  in  ARexx 


|CVa2i() 


Converts  ASCII  to  INT  | 


Syntax: 


(digits, value) 
Dl  DO 


CVa2i (buffer) 
AO 


Converts  from  ASCII  symbols  at  the  given  storage 
location  to  an  equivalent  4-byte  integer  value  (LONG). 
The  function  reads  ASCII  characters  until  a  character 
appears  that  is  not  a  number  or  until  an  overflow 
occurs.  The  function  returns  the  integer  value  and  the 
number  of  ASCII  characters  read. 
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|CVc2xQ 


|CVi2a() 


Syntax: 


Converts  CHAR  to  HEX  or  BINI 


Syntax:  error  =  CVc2x(outbuff, string, length, mode) 

DO  AO  Al  Dl  DO 

Changes  "length"  number  of  bytes  from  the  storage 
location  "string"  to  a  string  of  equivalent  hexadecimal 
or  binary  characters.  The  "mode"  is  either  -1  for  hex 
conversion  or  0  for  binary  conversion. 


Converts  INT  to  ASCII  | 


( length, pointer ) 
DO     AO 


CVi2a (buff er, value, digits ) 
AO     DO    Dl 


|CVi2arg() 


Changes  the  prefixed  integer  value  in  DO  to  the 
corresponding  decimal  number.  The  "buffer"  is  the 
target  for  the  resulting  string  and  "digits"  is  the 
maximum  number  of  characters  to  be  written.  The 
function  returns  "length",  the  actual  number  of 
characters  copied,  and  "pointer"  the  new  "buffer" 
pointer. 

Converts  INT  to  ASCII  arg  stfiiigl 


Syntax: 


argstring  =  CVi2arg (value) 
DO  DO 

AO 
(CCR) 

Changes  the  "LONG"  value  in  DO  to  a  string  and 
creates  a  Rexx  arg  structure.  The  return  value  is  a 
pointer  to  the  arg  string  structure;  or  0  if  an  error 
occurred.  The  structure  created  with  this  manipulation 
can  be  released  with  DeleteArgstring(). 
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|CVi2az() 

Syntax: 


lCVs2i() 


|CVx2c() 
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Converts  INT  with  leading  zeros  to  ASCII| 


( length , pointer ) 
DO      AO 


CVi2az (buffer, value, digits) 
AO     DO    Dl 


Changes  the  prefixed  integer  value  in  DO  to  the 
corresponding  decimal  number.  The  "buffer"  is  the 
target  for  the  resulting  string  and  "digits"  is  the 
maximum  number  of  characters  to  be  written.  If 
necessary,  zeros  are  added  to  the  left  in  order  to  reach 
the  number  of  characters  to  be  written.  The  function 
returns  "length",  the  actual  number  of  characters  copied, 
and  "pointer"  the  new  "buffer"  pointer. 

Converts  string  structure  to  INT| 


Syntax:  (error, value)    =  CVs2i(ss) 

DO  Dl  AO 

"ss"  is  a  pointer  to  a  string  structure.  The  function 
returns  the  value  of  the  string  as  "LONG"  in  Dl.  "Error" 
is  47  if  an  error  occurs;  this  is  the  code  for  "arithmetic 
conversion  error". 


Converts  HEX  or  BIN  to  CHAR| 


Syntax: 


error  =  CVx2c (outbuff, string, length,mode) 
DO  AO       Al     DO    Dl 

Changes  "string",  which  must  be  a  valid  hexadecimal  or 
binary  number  to  the  corresponding  character.  If 
"mode"  is  -1,  hex  is  to  be  expected;  or,  if  it's  0,  binary 
numbers.  There  can  be  spaces,  but  only  at  the  byte 
limits.  "Length"  indicates  the  number  of  bytes  to  be 
written  to  "outbuff.  "Error"  is  47  if  an  error  occurs;  this 
is  the  error  code  for  "arithmetic  conversion  error". 


ErrorMsgQ 


Calculates  the  error  message  from 
the  error  number 


Syntax:  (bool,ss)   =  ErrorMsg ( code ) 

DO  AO  DO 
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Returns  an  English  error  message  for  the  given  error 
code  as  a  pointer  to  a  string  structure.  "Bool"  is  -1  if 
"code"  is  not  a  valid  ARexx  error  code;  otherwise  it's  a 
0.  Undefined  error  codes  return  the  ominous 
"undiagnosed  internal  error". 

[ToUpperO  Converts  ASCII  to  capital  letters! 

Syntax:  upper  =  ToUpper ( char ) 

DO  DO 

Converts  ASCII  symbols  to  capital  letters,  working  only  with  DO. 

10.4.4        ARexx  Resource  Handling 

[AddClipNodeQ  Sets  up  a  clip  node  I 

Syntax:  node  =  AddClipNode( list .name, length, value) 

DO  A0  Al  DO  Dl 

AO 
(CCR) 

Creates  a  clip  node  and  binds  it  to  the  list  specified  with 
the  header  "list".  "Name"  is  a  pointer  to  a  name  string 
that  ends  with  zero;  "value"  is  a  pointer  to  the  storage 
area.  The  result  is  a  pointer  to  the  newly  created  node, 
or  zero  if  something  went  wrong. 

The  RemClipNodeO  function  deletes  a  node  created 
with  this  function.  Clip  nodes  can  be  held  in  a  resource 
list,  mixed  with  other  nodes  that  are  all  dissolved  with 
RemRsrcList(). 

[AddRsrcNodeQ  Adds  a  resource  node| 

Syntax:  node  =  AddRsrcNode (list, name, length) 

AO  AO  Al  DO 

AO 
(CCR) 

Creates  an  ARexxRsrc  structure  and  binds  it  to  the  list 
indicated  by  the  header  "list".  "Name"  is  a  pointer  to  a 
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string  closed  with  a  zero,  which  is  set  up  as  a  copy  of 
the  NodeName  slot  in  the  structure.  The  "length"  is  the 
size  of  the  entire  node  entered  into  the  structure  so  that 
it  can  be  removed  later  with  RemRsrcNode().  The  result 
is  a  pointer  to  the  newly  created  node,  or  zero  if  an  error 
occurred. 

IClearMemQ  Deletes  a  storage  area| 

Syntax:  ciearMem (address , length) 

AO  DO 

Deletes  a  storage  area  from  "address"  and  "length"  is 
number  of  bytes.  The  value  for  "address"  must  be  even 
and  "length"  must  be  a  multiple  of  four.  AO  is  preserved. 

IClearRexxMsgQ  Deletes  arg  strings  from  a  message! 

Syntax:  clearRexxMsg (msgptr , count ) 

AO  DO 

Releases  one  or  several  arg  strings  from  a  Rexx  message 
and  deletes  their  entries.  "Count"  is  the  number  of 
entries  to  be  released  and  can  be  set  to  values  smaller 
than  16  in  order  to  save  some  entries  for  your  own  use. 


IClosePublicPortQ  Releases  a  port  resource  node| 

Syntax:  closePublicPort (node) 

AO 

Closes  a  message  port  and  releases  its  resource  node 
that  must  have  been  created  with  OpenPublicPort(). 

I  Create  ArgStringQ  Creates  an  arg  string  structure  | 

Syntax:  argstring  =  CreateArgString (string, length) 

DO  AO  DO 

AO 
(CCR) 
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Generates  an  ARexx  arg  structure  and  copies  the  given 
string  into  it.  The  "argstring"  is  a  pointer  to  the  string 
buffer  of  the  structure  and  can  be  treated  like  a  normal 
string  pointer,  since  it  also  contains  information  about 
string  length,  structure  length,  and  the  hash  value  with 
negative  offsets  in  front  of  the  string. 


|  CreateRexxMessageQ 


Creates  an  ARexx  message  structure  | 


Syntax: 


msgptr  =  CreateRexxMessage (replyport, extension, host) 
DO  AO  Al      DO 

AO 

(CCR) 

Generates  an  ARexx  message  structure  that  is  a  normal 
EXEC  message  structure  with  additional  entries  for 
function  arguments  and  return  values.  The  "replyport"  is 
a  pointer  to  a  public  or  private  message  port  and  must 
be  specified  so  the  message  can  be  answered.  The 
"extension"  and  "host"  are  pointers  to  strings,  values  for 
file  recognition  and  the  address  of  the  external 
environment. 

Additional  entries  in  the  structure  can  be  inserted  later. 
The  interpreter  only  alters  the  entries  for  resultl  and 
result2. 


CurrentEnvQ 


Calculates  a  pointer  to  the  current 
active  environment 


entl 
ent| 


Syntax:  envptr  =  CurrentEnv(rxtptr) 

DO  AO 

Returns  a  pointer  to  the  current  storage  environment 
that  belongs  to  the  given  ARexx  program.  The  value 
"rxptr"  is  a  pointer  to  the  Rexx  task  structure  of  the 
corresponding  program  and  can,  for  example,  be 
calculated  from  a  message  that  was  sent  by  this 
program. 
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I  Delete ArgstringQ  Releases  an  arg  string  structure  | 

Syntax:  DeleteArgstring (argstring) 

AO 

Deletes  an  ARexx  arg  structure.  The  structure  contains 
its  own  length  with  a  negative  offset  arg  string  pointer. 

IDeleteRexxMsgQ  Deletes  an  ARexx  message  structure | 

Syntax:  DeleteRexxMsg (packet ) 

AO 

Releases  an  ARexx  message  structure.  The  value 
contained  in  the  structure  is  used  to  determine  its  size. 
All  arg  strings  in  it  must  already  have  been  released 
before  the  call  to  this  function. 

IFillRexxMsgQ  Fills  in  arg  strings  in  a  Rexx  message | 

Syntax:  bool  =  FillRexxMsg(msgptr,count,mask) 

DO  AO  DO  Dl 

(CCR) 

Converts  up  to  16  arguments  and  fills  them  into  the 
Rexx  message  "msgptr".  The  structure  must  already  be 
initialized  and  the  argument  slots  must  either  be  pointers 
to  strings  closed  with  zeros  or  integer  values.  The 
"count"  indicates  the  number  of  argument  slots  to  be 
converted  (usually  all  of  them,  except  special  purpose 
slots);  the  bits,  0-15,  in  "mask"  determine  if  a  pointer  (0) 
or  an  integer  (1)  is  in  the  slot.  The  result  is  -1  if  all 
arguments  were  successfully  converted.  If  an  error 
occurred,  all  previously  installed  arg  strings  are  released 
and  0  is  returned. 

iFindRsrcNodeQ  Finds  a  resource  nodel 

Syntax:  node  =  FindRsrcNode (list, name, type) 

DO  AO  Al        DO 

AO 
(CCR) 
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IKreePortQ' 


Searches  in  the  given  "list"  for  the  first  node  with  the 
desired  "name".  The  value  of  "list"  must  be  a  pointer  to 
an  EXEC  list  header  and  "name"  must  be  a  string  that 
ends  with  a  zero.  If  "type"  is  0,  not  all  nodes  are 
examined,  only  those  of  the  given  type.  The  result  is  a 
pointer  to  the  node,  or  0  if  the  name  was  not  found. 


Closes  a  message  port 


Syntax:  FreePort (port ) 

A0 


|FreeSpaceQ 


Releases  all  signal  bits  that  belong  to  a  port  and  closes 
it.  A  port  must  be  closed  by  the  same  task  that  opened 
it,  since  the  arrangement  of  signal  bits  is  task  specific 
and  only  available  in  the  task  control  block.  The  storage 
area  that  belongs  to  the  port  is  not  released. 

Releases  internal  storage  area] 


Syntax: 


FreeSpace ( envptr , block , length) 
A0         Al     DO 


KietSpaceQ" 


Syntax: 


Returns  storage  areas  reserved  with  GetSpace()  to  the 
interpreter.  The  "envptr"  points  to  the  current  disk 
storage  environment  and  can  be  queried  with 
CurrentEnv(). 


Reserves  internal  storage  area] 


block  =  GetSpace (envptr, length) 
DO  A0       DO 

A0 

(CCR) 


Reserves  a  storage  area  of  the  interpreter.  This  storage 
area  is  managed  by  the  interpreter  and  returned  to  the 
operating  system  at  the  end  of  the  program.  "Envptr" 
points  to  the  current  disk  storage  environment  for  the 
program. 
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Unit  List  0 


Syntax: 


See  also: 


This  function  is  also  used  by  the  interpreter  to  obtain 
small  storage  areas  for  string  contents;  it's  always  useful 
for  small  storage  areas  that  are  only  needed  until  the 
end  of  the  program.  The  programmer  does  not  have  to 
worry  about  releasing  these  storage  areas  until  they  get 
too  large. 

Builds  a  list  header  structure] 


Syntax:  initList (list) 

AO 

Initializes  an  EXEC  list  header  structure. 
|InitPort()  Initializes  a  message  port| 


(signal, port)  =  InitPort (port, name) 
DO        Al  AO      Al 

Initializes  a  message  port  structure  that  was  previously 
created.  The  task  ID  of  the  calling  program  is  used  in  the 
MP_SIGTASK  slot  and  a  signal  bit  is  used.  "Signal"  is 
the  used  bit,  or  -1  if  none  were  free.  The  "port"  is  a 
pointer  to  the  message  port  structure  and  "name"  is  a 
pointer  to  a  string  that  is  to  be  used  in  the  MP_NAME 
slot.  The  port  address  is  after  the  call  to  Al,  which  is 
practical  if  you  want  to  execute  the  EXEC  function 
AddPort()  in  order  to  make  the  port  public. 

FreePortO 


|IsRexxMsg() 


Tests  a  message  | 


Syntax:  bool  =  IsRexxMsg(msgptr) 

DO  AO 

Determines  if  the  message  that  "msgptr"  is  pointing  to  is 
actually  a  Rexx  message.  This  is  determined  by  its  name: 
Rexxmessages  have  a  pointer  to  a  hard-coded  string 
containing  "REXX"  in  the  LN_NAME  slot.  The 
returned  value  is  -1  if  it's  a  Rexx  message,  otherwise  0. 
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UsSymbolQ" 


Is  the  string  a  valid  symbol?  | 


Syntax: 


(code, length) 
DO  Dl 


IsSymbol (string) 

AO 


Investigates  the  given  string.  If  it's  a  valid  ARexx 
symbol,  the  corresponding  code  is  returned  in  DO,  or  0  is 
returned  if  the  string  began  with  an  invalid  character. 
The  value  "length"  returns  the  length  of  the  symbols 
found. 


|  Length  A  rgstringQ" 


Calculates  the  length  of  an  arg  string  | 


Syntax: 


length 
DO 


LengthArgstring (argptr) 
AO 


IListNamesQ 


This  is  the  recommended  method  to  determine  the 
length  of  an  arg  string.  "Argptr"  points  to  the  arg  string 
structure;  "length"  is  the  length  of  the  strings  in  it. 

Lists  node  names  in  an  arg  string] 


Syntax:  argstring  =  ListNames (list, separator) 

DO  AO  DO 

AO 
(CCR) 

Goes  through  the  given  list  and  copies  all  nodes  in  it  to 
an  arg  string  structure.  The  "list"  must  point  to  an  EXEC 
list  header.  The  "separator"  is  an  ASCII  character 
inserted  between  the  individual  names.  While  the  list  is 
investigated,  task  switching  is  shut  off  with  Forbid(). 
This  ensures  control  of  the  structures,  even  for  global 
and  system  lists.  Arg  string  structures  can  be  released 
with  DeleteArgstringO. 


LockRexxBaseQ 


Protects  a  global  resource  from 
data  write  calls 


Syntax: 


LockRexxBase (resource) 
DO 
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Protects  the  given  resource  from  any  data  write  access. 
"Resource"  is  a  constant  that  shows  what  lock  is 
requested: 


RRT  ANY 

0 

An 

RRT_LIB 

1 

Function  libraries 

RRT.PORT 

2 

Public  ports 

RRT_FILE 

3 

File  10  Buffer  (IOBuff) 

RRT  HOST 

4 

External  function  environment 

RRT_CLIP 

5 

The  Clip  list 

Writing  access  to  global  resources  are  normally  handled 
via  the  Rexx  master  procedure  which  runs  with  higher 
priority  in  order  to  ensure  complete  control.  This  is 
another  reason  not  to  run  ARexx  programs  with  higher 
priority  than  the  Rexx  master  procedure. 


See  also:  UnlockRexxBase() 

IQpenPublicPortQ 


Creates  a  port  resource  node] 


Syntax:  node  =  OpenPublicPort (list, name) 

DO  AO  Al 

Al 
(CCR) 

Opens  a  public  message  port  with  the  name  given  in 
"name"  and  binds  it  to  the  list  shown  by  the  header  in 
"list".  The  message  port  is  also  added  to  the  system  list 
of  ports.  See  also:  ClosePublicPortQ. 


IRemClipNodeQ" 


Releases  a  clip  node) 


Syntax:  RemClipNode ( node ) 

AO 

Cuts  the  given  clip  node  from  the  clip  list  and  releases 
the  storage  area  assigned  to  it.  This  function  is 
automatically  carried  out  by  RemRsrcNode()  and 
RemRsrcListO  for  a  clip  node. 

See  also:  AddClipNodeQ,  RemRsrcNodeQ,  RemRsrcListO 
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I  RemRsrcListQ  Releases  a  resource  listl 

Syntax:  RemRsrcList ( list ) 

AO 

Releases  all  nodes  in  the  given  list,  all  of  which  must  be 
RexxRsrc  structures.  For  each  node,  the  "auto-delete" 
function  is  called. 

IRemRsrcNodeQ  Removes  a  resource  node| 

Syntax:  RemRsr cNode ( node ) 

AO 

Removes  the  given  node  from  its  list.  If  an  "auto-delete" 
function  is  specified,  it's  executed  first.  The  name  string 
in  it  is  also  released. 

|UnlockRexxbase()  Releases  a  global  resource! 

Syntax:  UnlockRexxBase (resource) 

DO 

Releases  the  given  resource.  Each  call  to 
LockRexxBase()  should  be  followed  by  this 
counterpart.  The  definition  of  the  resource  constants  is 
explained  in  the  section  on  LockRexxBase(). 
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10.5  The  RexxBase  Lists 


All  structures  managed  by  the  Rexx  master  procedure  are  noted  in  the 
basic  structure  of  the  ARexx  system  library  and  can  be  found  by  other 
programs.  The  task  list  in  RexxBase  contains  a  pointer  to  the  global 
structures  for  all  currently  running  ARexx  programs.  Individual  task 
structures  are  linked  by  the  message  ports  in  them. 

The  Rexx  task  structure  is  the  global  data  structure  for  an  ARexx 
program  and  its  initial  storage  environment.  All  other  storage  areas  are 
added  to  the  lists  contained  here.  By  doing  this,  the  internal  data  of  each 
ARexx  program  can  be  reached  using  the  RexxBase  pointer. 

There  are  two  functions  of  the  ARexx  system  library,  LockRexxBase() 
and  UnlockRexxBase().  The  base  structure  should  always  be  protected 
from  access  with  a  lock  before  looking  at  a  list  and  reading  data. 

Usually,  it's  not  necessary  to  access  these  structures  directly,  since  there 
are  corresponding  functions  in  the  ARexx  system  library  for  all  necessary 
operations  which  should  be  used  for  that  purpose.  Direct  control  is  not 
recommended. 
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10.6   ARexx  Error  Messages 

If  the  ARexx  interpreter  discovers  a  program  error,  an  error  code  is 
returned  indicating  the  nature  of  the  problem.  Normally  an  error  code 
displays  the  program  line  in  which  it  was  encountered,  and  a  short 
descriptive  error  message.  If  the  SYNTAX  interrupt  was  not  enabled,  the 
program  ends.  The  SYNTAX  interrupt  can  catch  most  errors  so  that  the 
program  itself  can  take  counter-measures.  Some  errors  still  develop  in 
areas  outside  of  the  ARexx  jurisdiction  and  cannot  be  caught. 

There  is  a  value  attached  to  each  error  code  showing  the  error  level  that's 
returned  as  the  primary  result.  The  error  code  itself  appears  as  the 
secondary  result. 


Error  code:  1  Error  level:  5  Message:  Program  not 

found 


The  given  program  could  not  be  found  or  is  not  an  ARexx  program. 
ARexx  programs  must  always  start  with  "/*".  This  cannot  be  trapped 
with  the  SYNTAX  interrupt. 


Error  code:  2            Error  level:  10  Message:  Execution 
halted 


The  program  ended  because  a  Ictnl  +(£)  break  or  an  external  HALT 
request  was  given.  This  error  can  be  caught  with  the  HALT  interrupt. 


Error  code:  3  Error  level:  20  Message:  Insufficient 

memory 


The  interpreter  was  unable  to  receive  enough  memory  space  for  an 
operation.  Since  all  operations  of  the  interpreter  usually  need  some 
storage  access,  this  error  cannot  usually  be  caught  with  the  SYNTAX 
interrupt. 
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Error  code:  4  Error  level:  10  Message:  Invalid 

character 


Invalid  characters  were  located  in  the  source  code.  Control  codes  and 
other  special  characters  can  only  be  used  in  hexadecimal  or  binary 
strings  within  a  program.  This  error  cannot  be  caught  with  the  SYNTAX 
interrupt. 


Error  code:  5  Error  level:  10  Message:  Unmatched 

quote 


A  string  delimiter  ('  or  ")  is  omitted.  Each  string  must  be  enclosed  with  the 
same  character  with  which  it  began.  This  error  cannot  be  caught  with  the 
SYNTAX  interrupt. 


Error  code:  6            Error  level:  10  Message:  Unterminated 
comment 


The  characters  ("*/")  that  indicate  the  end  of  a  comment,  were  not  found. 
Please  note  that  comments  can  be  nested,  so  every  "/*"  must  be  followed 
by  a  "*/".  This  error  cannot  be  caught  with  the  SYNTAX  interrupt. 


Error  code:  7            Error  level:  10                  Message:  Clause  too 
long 


A  clause  was  too  long  to  be  written  to  the  interpreter's  internal  interim 
storage  area.  The  maximum  length  (without  multiple  spaces  and 
commentaries)  is  800  characters.  The  questionable  clause  should  be 
divided  into  two  or  more  parts.  This  error  cannot  be  caught  with  the 
SYNTAX  interrupt. 

|  Error  code:  8  Error  level:  10  Message:  Invalid  token  | 

An  invalid  token  was  encountered  or  a  clause  could  not  be  classified. 
This  error  cannot  be  caught  with  the  SYNTAX  interrupt. 


Error  code:  9            Error  level:  10                  Message:  Symbol  or 
string  too  long 


An  attempt  was  made  to  generate  a  string  with  more  than  65,535 
characters. 
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Error  code:  10          Error  level:  10         Message:  Invalid  message 
packet 


In  a  message  received  by  the  Rexx  master  procedure,  an  invalid  action 
code  was  encountered.  It  was  returned  with  no  changes.  This  error  is 
externally  created  and  cannot  be  caught  with  the  SYNTAX  interrupt. 


Error  code:  11          Error  level:  10                   Message:  Command 
string  error 


A  command  string  was  incorrect.  This  error  is  externally  created  and 
cannot  be  caught  with  the  SYNTAX  interrupt. 


Error  code:  12  Error  level:  10  Message:  Error  return 

from  function 


An  external  function  returned  an  error  code  not  equal  to  zero.  It's 
possible  that  the  parameters  were  not  correctly  passed. 


Error  code:  13  Error  level:  10  Message:  Host 

environment  not  found 


The  message  port  indicated  by  an  address  was  not  found.  If  the  name  is 
correctly  written  (including  capitalization),  is  the  desired  function 
environment  active? 


Error  code:  14          Error  level:  10                   Message:  Requested 
library  not  found 


The  program  was  not  able  to  open  a  library  entered  in  the  library  list.  If 
ADDLIBO  was  called  with  the  correct  name,  was  the  correct  version 
number  called?  Is  the  library  in  the  LIBS:  directory? 


Error  code:  15          Error  level:  10    ~~        Message:  Function  not 
found 


A  function  was  called  that  was  not  in  any  of  the  libraries  added  with 
ADDLIB()  and  also  not  found  as  an  external  program.  Is  the  spelling 
correct?  Was  the  library  bound  with  ADDLIB()  to  the  list? 
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Error  code:  16          Error  level:  10  Message:  Function  did 
not  return  value 


A  function  was  completed  without  delivering  a  result  string  and  without 
encountering  an  error.  Was  the  function  correctly  programmed?  If  it  was 
accessed  with  CALL  this  can  be  avoided. 


Error  code:  17          Error  level:  10           Message:  Wrong  number 
of  arguments 


A  function  expecting  more  or  fewer  arguments  was  called.  This  error  also 
occurs  if  a  built-in  or  an  external  function  is  called  with  more  arguments 
than  the  message  can  contain  (max.  15). 


Error  code:  18  Error  level:  10  Message:  Invalid 

argument  to  function 


An  argument  that  does  not  agree  with  the  function  was  passed,  or  a 
necessary  argument  was  omitted. 


Error  code:  19          Error  level:  10                        Message:  Invalid 
procedure 


A  procedure  call  occurred  at  the  wrong  location.  Either  it  was  not  in  an 
internal  function,  or  it  occurred  twice  in  a  function. 


Error  code:  20          Error  level:  10  Message:  Unexpected 
THEN  or  WHEN 


A  THEN  or  WHEN  command  occurred  at  the  wrong  location.  The 
WHEN  command  is  only  valid  within  the  area  of  a  SELECT  command 
and  THEN  must  directly  follow  an  IF  or  WHEN. 


Error  code:  21  Error  level:  10  Message:  Unexpected 

ELSE  or  OTHERWISE 


An  ELSE  or  OTHERWISE  command  occurred  at  the  wrong  location.  An 
OTHERWISE  command  is  only  valid  within  the  area  of  a  SELECT 
command.  ELSE  is  only  available  after  a  THEN  branch  of  an  IF 
command. 
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Error  code:  22          Error  level:  10  Message:  Unexpected 
BREAK,  LEAVE,  or  ITERATE 


The  BREAK  command  is  only  valid  in  a  DO  group  or  in  commands  that 
are  executed  with  INTERPRET.  Commands  to  LEAVE  or  ITERATE  are 
only  valid  in  a  DO  loop. 


Error  code:  23  Error  level:  10  Message:  Invalid 

statement  in  SELECT 


In  the  area  of  a  SELECT  command,  an  illegal  construction  was 
encountered.  Only  WHEN-THEN  and  OTHERWISE  constructions  are 
valid. 


Error  code:  24          Error  level:  10                  Message:  Missing  or 
multiple  THEN 


A  THEN  clause  was  expected,  but  not  found,  or  a  THEN  appeared 
without  IF  or  WHEN. 


Error  code:  25  Error  level:  10  Message:  Missing 

OTHERWISE 


No  WHEN  clause  in  the  area  of  a  SELECT  command  was  successful  and 
no  OTHERWISE  was  found. 


Error  code:  26          Error  level:  10                  Message:  Missing  or 
unexpected  END 


The  source  text  ended  without  closing  a  DO  or  SELECT  group  with 
END,  or  an  END  clause  was  found  outside  such  a  group. 


Error  code:  27          Error  level:  10  Message:  Symbol 
mismatch 


The  symbol  specified  with  an  END,  ITERATE,  or  LEAVE  command  did 
not  agree  with  the  index  variable  of  the  appropriate  DO  group. 
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Error  code:  28          Error  level:  10                 Message:  Invalid  DO 
syntax 


The  interpreter  found  an  error  in  a  DO  command:  If  TO  or  BY  are 
specified,  the  index  variable  must  be  initialized  and  the  expression  after 
FOR  must  evaluate  to  a  positive  integer. 


Error  code:  29  Error  level:  10  Message:  Incomplete  IF 

or  SELECT 


An  IF  or  SELECT  group  ended  before  all  of  the  necessary  constructions 
were  encountered.  Perhaps  a  THEN,  ELSE,  or  OTHERWISE  construction 
is  omitted. 


Error  code:  30  Error  level:  10  Message:  Label  not 

found 


A  jump  marker  specified  in  a  SIGNAL  command  or  searched  for  with  a 
SIGNAL  interrupt,  could  not  be  found  in  the  source  code.  Interactive 
commands  or  marks  established  in  an  interpreter  command  are  usually 
not  found. 


Error  code:  31          Error  level:  10                       Message:  Symbol 
expected 


At  a  location  where  only  a  symbol  is  appropriate,  an  invalid  token  was 
found.  The  commands  DROP,  END,  LEAVE,  ITERATE  and  UPPER  can 
only  be  followed  by  symbols  and  create  this  message  if  anything  but  a 
symbol  is  found  or  a  necessary  symbol  is  omitted. 


Error  code:  32         Error  level:  10                  Message:  Symbol  or 
string  expected 


At  a  location  where  only  a  symbol  or  string  is  permitted,  an  invalid  token 
was  found. 


Error  code:  33          Error  level:  10                       Message:  Invalid 
keyword 


A  symbol  in  a  command  was  recognized  as  a  key  word  but  is  not  valid  at 
this  location. 
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Error  code:  34  Error  level:  10 


Message:  Required 
keyword  missing 


A  certain  keyword  was  expected  by  a  command  and  was  not  found.  This 
message  occurs  if  none  of  the  keywords  for  the  individual  interrupts 
(such  as  SYNTAX)  follows  a  SIGNAL  ON  command. 


Error  code:  35  Error  level:  10 


Message:  Extraneous 
characters 


A  seemingly  correct  command  was  executed  but  further  characters  were 
found  following  it. 


Error  code:  36 


Error  level:  10 


Message:  Keyword 
conflict 


Two  mutually  exclusive  keywords  occurred  in  the  same  command  or  a 
key  word  was  encountered  twice. 


Error  code:  37 


Error  level:  10 


Message:  Invalid 
template 


The  template  specified  in  an  ARG,  PARSE,  or  PULL  command  was 
invalid. 


Error  code:  38          Error  level:  10          Message:  Invalid  TRACE 
request 


The  keyword  for  a  TRACE  command  or  an  argument  for  the  TRACE() 
function  was  not  valid. 


Error  code:  39 


Error  level:  10 


Message:  Uninitialized 
variable 


An  attempt  was  made  to  read  an  uninitialized  variable.  This  message 
appears  only  when  the  NO  VALUE  interrupt  is  enabled. 


Error  code:  40 


Error  level:  10 


Message:  Invalid 
variable  name 


An  attempt  was  made  to  assign  a  value  to  a  constant. 
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Error  code:  41          Error  level:  10                       Message:  Invalid 
expression 


During  an  evaluation  of  an  expression,  an  error  occurred.  Possibly  an 
operator  was  not  used  correctly  or  invalid  characters  appeared.  This  error 
only  appears  when  an  expression  is  analyzed;  expressions  that  are 
jumped  over  are  not  checked. 


Error  code:  42          Error  level:  10                Message:  Unbalanced 
parentheses 


An  expression  was  encountered  that  did  not  have  the  same  number  of 
open  and  close  parentheses  marks. 


Error  code:  43  Error  level:  10  Message:  Nesting  limit 
exceeded 


The  number  of  nested  sub-expressions  was  higher  than  32.  The 
expression  should  be  divided  into  several  partial  expressions. 


Error  code:  44          Error  level:  10  Message:  Invalid 
expression  result 


The  result  of  an  expression  was  not  valid.  This  error  is  created  if  an 
expression  in  a  DO  command  does  not  lead  to  a  numeric  result. 


Error  code:  45          Error  level:  10                  Message:  Expression 
required 


An  expression  is  omitted  in  a  necessary  location.  An  example  is  that  after 
SIGNAL  an  expression  must  follow,  unless  ON  or  OFF  was  specified. 


Error  code:  46  Error  level:  10  Message:  Boolean  value 
not  0  or  1 


The  result  of  an  expression  should  be  a  Boolean  result,  but  a  value  that  is 
not  0  or  1  occurred. 
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Error  code:  47  Error  level:  10  Message:  Arithmetic 

conversion  error 


During  an  operation  that  requires  numeric  operands,  a  non-numeric 
operand  was  encountered.  A  hex  or  binary  string  with  errors  also  leads 
to  this  error  message. 


Error  code:  48          Error  level:  10                        Message:  Invalid 
operand 


An  operation  was  attempted  with  an  invalid  operand.  This  error  occurs 
when  dividing  by  0  or  when  trying  to  display  fractional  Exponents  (that 
are  not  supported  by  ARexx). 
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The  Amiga  3000  is  the  first  completely  new  model  Commodore  has 
introduced  since  the  Amiga  1000.  Unlike  the  A500  and  A2000,  which 
hardly  differed  from  their  predecessor  technologically,  the  A3000  is  a 
truly  new  development,  capable  of  holding  its  own  against  the  Intel 
80386-based  IBM-compatible  personal  computers;  in  some  areas  it  even 
surpasses  them. 

The  most  important  innovation  is  the  departure  from  the  68000  as  central 
processor.  Powerful  as  this  chip  was  in  comparison  to  its  counterpart, 
Intel's  80286,  a  databus  width  of  32  bits  has  since  become  the  standard. 
In  fact,  the  first  64-bit  microprocessor  has  already  appeared  —  the  80860 
introduced  in  1989  by  Intel. 

By  its  decision  to  base  the  new  Amiga  on  the  68030  processor, 
Commodore  has  achieved  the  best  possible  compromise  between  price, 
performance  and,  perhaps  most  importantly,  compatibility.  Commodore's 
software  developers  don't  have  to  worry  about  compatibility  problems 
between  the  68000  and  the  68030. 

It  is  safe  to  assume  that  the  majority  of  existing  software  will  run  on  the 
new  machine.  Any  problems  are  more  likely  to  be  related  to  the  new 
Kickstart  2.0  operating  system  than  to  the  new  hardware,  and 
fortunately  the  A3000  will  also  run  Kickstart  1.3. 

"Dirty"  programs  unable  to  cope  with  the  6-  to  8-fold  increase  in 
computing  speed  can  always  turn  to  the  GURU  generator.  This  same 
problem  presented  itself  earlier,  however,  with  the  widespread  use  of 
68020  and  68030  cards  in  the  A2000.  So  programmers  had  enough  time, 
before  the  A3000  was  introduced,  to  correct  bad  programming  habits 
learned  on  the  C64  and  adapt  their  software  to  the  new  generation  of 
computers. 

Linked  with  the  new  processor  are  the  FPU  68881  and  68882  (in  the  16 
and  25  MHz  models,  respectively).  These  floating  point  processors  speed 
mathematical  routines  and  give  the  A3000  a  "computing"  power  (in  the 
truest  sense  of  the  word)  that's  suitable  for  a  scientific  workstation. 
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Another  important  improvement  over  the  A2000  is  the  built-in  hard  disk 
and  its  SCSI  bus,  which  also  enables  the  addition  of  CD-ROM  or  tape 
drives.  The  32-bit  SCSI  chip,  developed  by  Commodore  specifically  for 
this  purpose,  offers  adequate  speed  required  for  the  operation  of  modern 
storage  media. 

The  hard  disk  itself  comes  from  Quantum.  This  company  has  succeeded 
in  producing  a  drive  that  is  not  only  fast  and  reliable,  but  also  quiet.  Any 
user  who  has  dealt  with  the  grinding,  screeching  or  whistling  of  less 
adeptly  engineered  examples  of  mass  storage  technology  will  certainly 
appreciate  this.  (Unfortunately,  the  A3000  still  has  the  old  vacuum 
cleaner  noise,  although  it  does  run  at  a  whisper  compared  to  the  A2000.) 

Technically  speaking,  little  has  changed  in  the  area  of  graphics.  However, 
there  is  one  exception  so  crucial  that  it  could  be  considered  the  A3000's 
single  most  important  innovation.  This  is  the  flicker  fixer,  which  alleviates 
the  flickering  that  may  occur  when  a  screen  is  displayed  in  interlace 
mode  by  temporarily  storing  the  individual  half-pictures  (frames).  Many 
A2000  owners  have  purchased  such  a  flicker  fixer  because  it 
significantly  improves  the  display  quality. 

Moreover,  integration  of  the  Enhanced  Chip  Set  (ECS),  which  consists 
of  a  substantially  improved  Agnus  chip  and  a  new  Denise,  produces, 
even  without  the  flicker  fixer,  a  640  *  480  screen  with  a  refresh  rate  of 
60  Hz,  although  this  is  with  a  maximum  of  only  four  colors. 

All  the  new  features  mentioned  above  are  explained  in  detail  in  the 
following  sections,  both  from  a  hardware  standpoint  and  from  the 
programmer's  point  of  view.  The  familiar  A2000  features  that  have  not 
changed  in  the  A3000  are  also  discussed  in  detail. 
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The  heart  of  the  A3000,  the  68030  microprocessor,  is  the  product  of  a 
continuing  development  process  that  began  with  the  68000  in  1979.  So 
far  this  process  has  culminated  in  the  68040  and  further  advances  are 
sure  to  come.  Motorola  has  succeeded  (or  nearly  so,  at  least)  in 
maintaining  software  compatibility  across  this  entire  line  of  processors. 
The  performance  of  the  new  models  isn't  significantly  affected  when 
running  old  programs.  This  is  definitely  a  worthwhile  accomplishment. 
Motorola's  competitor,  Intel,  hasn't  been  able  to  do  the  same  with  the  86 
processor  series  for  the  PC. 

The  Forefather:  MC  68000 

When  it  was  introduced,  the  MC  68000  was  a  pioneering  product.  With 
astounding  foresight,  its  developers  gave  it  attributes  that  would  make  it 
the  forefather  of  an  entire  processor  family.  Specifically,  these  attributes 
are: 

A  universal  register  structure 

The  entire  68000  family  has  eight  data  registers  and  eight  address 
registers,  all  with  a  width  of  32  bits.  Except  for  the  distinction  between 
address  and  data  registers,  there  is  no  connection  between  a  register  and 
the  functions  for  which  it  may  be  used.  This  differs  many  other 
processors,  where,  for  example,  an  accumulator  is  designated  specifically 
for  computation  results,  or  an  index  register  specifically  for  table 
addressing.  With  such  a  design,  moving  data  from  one  register  to  another 
is  largely  eliminated.  The  greater  register  size  also  makes  it  unnecessary, 
in  computations  with  integers,  to  divide  a  value  over  more  than  one 
register.  Almost  all  computations  can  be  executed  in  a  single  instruction. 
This  structure  was  retained  with  the  68020,  since  it  is  fully  adequate  for  a 
true  32-bit  processor  also. 

Large  linear  address  space 

Although  the  address  space  of  the  68000  is  only  16  Megabytes,  all  its 
address  registers  are  32  bits  wide.  There  is  no  addressing  limitation,  so 
that  accommodating  the  68020's  address  space  of  four  Gigabytes  (an 
amount  still  generous  by  today's  standards)  was  a  simple  matter  of 
bringing  in  eight  more  address  lines.  A  data  field  can  be  quickly  accessed 
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by  loading  any  address  register  with  the  desired  base  address  and 
referencing  the  data  by  means  of  a  16-bit  displacement  value  added  to 
the  base.  This  saves  time  because  only  16  bits,  not  32,  must  be  loaded 
from  memory.  This  scheme  combines  the  advantages  of  a  large  linear 
(non-segmented)  address  space  and  quick  access  to  contiguous  data. 

Many  types  of  addressing 

Besides  the  "normal"  types  of  addressing,  such  as  absolute,  indirect  or 
immediate,  handled  by  almost  all  processors,  the  68000  is  capable  of 
indirect  addressing  with  displacement  as  well  as  PC-relative  addressing, 
in  which  data  is  referenced  relative  to  an  instruction  address.  This  also 
saves  time,  since  again  not  all  32  address  bits  are  required.  Another  type 
of  addressing  that  distinguishes  the  68000  from  its  competitors  is 
postincrement/predecrement  addressing.  In  this  method,  automatic 
increasing  or  decreasing  of  addresses  with  each  data  access  allows  any 
address  register  to  function  as  a  stack.  When  processing  sequential  data 
fields  with  postincrement  or  predecrement  addressing,  you  save  an 
instruction  by  not  having  to  compute  the  next  address. 

Other  types  of  addressing  were  also  introduced  with  the  68020.  These 
are  primarily  capable  of  speeding  up  programs  written,  for  example,  in  C, 
with  its  improved  compilers.  A  list  of  all  the  types  of  addressing  is  located 
in  Section  11.2. 

Team  performance:  68020,  FPU  &  MMU 

Besides  the  widening  of  the  address  and  data  buses  to  their  current  32 
bits,  another  improvement  in  the  68020  was  the  addition  of  a  universal 
coprocessor  interface  and  the  accompanying  coprocessor,  the  FPU 
(Floating  Point  Unit)  68881.  The  68020  completely  takes  over  the 
addressing  of  instructions  and  data  for  its  coprocessor.  Machine- 
language  instructions  for  the  FPU  are  simply  mixed  with  those  of  the 
main  processor.  From  a  software  standpoint,  the  68020  forms  a  closed 
unit  with  its  coprocessor.  The  exact  design  and  programming  of  this  chip 
are  described  in  more  detail  later  in  this  chapter.  The  68020/30  +  FPU 
team  is  adept  at  screen  processing  and  other  computation-intensive 
tasks. 

The  68020  system  has  another  coprocessor  in  the  form  of  the  Paged 
Memory  Management  Unit  (PMMU).  This  unit  is  responsible  for 
controlling  memory  access  of  the  various  processes  by  creating  a  virtual 
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address  space  for  each  one.  You're  probably  already  familiar  with  the 
GURU.  Your  experiences  should  help  demonstrate  the  usefulness  of  this 
concept.  Taking  C  as  an  example,  suppose  an  uninitialized  pointer  is 
used  to  assign  a  value  to  a  variable.  It  will  erroneously  point  to  an 
address  in  memory  determined  by  the  value  in  the  stack  where  it  was 
initially  set  by  the  compiler.  If  this  is  an  area  of  memory  being  used  by  the 
operating  system,  the  GURU  will  come  to  call. 

The  only  protection  the  68000  offers  against  such  encroachment  is  the 
differentiation  between  supervisor  and  user  mode.  Memory  can  be 
divided  by  hardware  means  into  two  parts,  one  of  which  can  be  accessed 
only  in  supervisor  mode.  This  technique,  though,  has  two  serious 
disadvantages.  First,  while  the  operating  system  is  now  safe,  user 
programs  can  still  be  clobbered,  which  makes  a  multitasking,  and 
obviously  a  multiuser  system,  impossible. 

Secondly,  such  a  technique  requires  a  fixed  and  permanent  dividing  of 
memory,  in  which  expensive  RAM  cannot  be  used  to  its  fullest 
advantage.  The  maximum  amount  needed  by  the  operating  system  must 
always  be  reserved  for  it  in  the  supervisor  area.  Though  part  of  this  is 
used  only  occasionally,  it  is  never  available  to  user  programs.  In  short, 
flexible  memory  management  adapted  to  changing  requirements  is  not 
possible. 

For  these  reasons,  little  use  has  been  made  of  this  capability  of  the 
68000.  Even  in  the  Amiga,  supervisor  and  user  memory  are  identical, 
with  the  disadvantage  that  any  task  can  crash  the  system. 

In  the  68020  and  68030,  this  problem  is  solved  by  the  PMMU. 
Switching  between  processor  and  memory,  it  checks  every  access, 
providing  protection  to  all  areas  from  even  the  most  ill-mannered  task. 

Actual  computing  functions  are  also  faster  in  the  68020.  A  barrel  shifter 
was  integrated  for  shift  operations,  making  them  equally  fast,  whether  a 
register  is  shifted  by  a  single  bit  or  by  15  bits. 

Since  the  68020  functions  at  a  clock  frequency  of  20  MHz  and  is 
internally  faster,  it  processes  significantly  more  data  and  instructions  from 
main  memory  than  the  68000.  RAM  must  be  very  fast  in  order  for  the 
processor  to  work  at  maximum  speed.  You  would  also  like  RAM  to  be  as 
large  as  possible.  Unfortunately  these  two  requirements  can  add  up  to 
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considerable  expense.  For  this  reason,  the  68020  includes  a  cache 
memory.  This  is  a  small,  fast  storage  area  (64  long  words  or  256  bytes)  in 
which  the  most  recently  used  instruction  is  saved.  With  a  second 
reference  to  this  instruction,  for  example  another  execution  of  a  loop,  the 
68020  can  fetch  the  instruction  directly  from  the  cache  without  having 
to  access  memory.  This  caching  enables  the  processor  to  utilize  less 
expensive  memory  chips  with  almost  the  same  speed  as  would  be 
attained  with  fast  RAM. 
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Because  of  the  advances  in  semiconductor  technology,  more  function 
blocks  can  be  included  on  a  single  chip.  The  MMU,  which  was  a 
coprocessor  for  the  68020,  is  now  integrated  into  the  68030. 
Furthermore,  the  256-byte  instruction  cache  is  accompanied  in  the 
68030  by  a  data  cache  of  the  same  size. 

The  bus  controller,  which  manages  communication  between  memory  and 
the  CPU,  is  also  improved.  It  can  now  move  data  into  the  cache 
independent  of  the  processor  and,  with  sufficiently  fast  RAM,  transfer 
data  over  the  bus  at  a  rate  almost  double  that  of  the  68020  running  at 
the  same  clock  frequency. 

This  concept  of  parallel  processing  is  actually  what  distinguishes  the 
68030  from  its  predecessor.  Because  of  the  separation  of  the  address  and 
data  buses  between  the  caches  and  the  processing  unit  (Harvard 
Architecture),  instructions  can  be  processed  partially  in  parallel.  While 
the  last  operation's  data  is  still  being  processed,  the  next  instruction  is 
decoded  and  prepared.  The  bus  controller  loads  the  data  from  RAM  and 
the  MMU  translates  and  validates  the  addresses. 

The  following  sections  describe  the  various  function  blocks  and  their 
programming.  However,  since  the  subject  of  this  book  is  the  Amiga 
instead  of  the  68030,  we  won't  provide  detailed  information.  We  will 
discuss  primarily  the  differences  and  improvements  that  distinguish  the 
68030  from  the  68000. 

If  you're  not  familiar  with  machine  language,  refer  to  one  of  the  many 
books  on  programming  the  68000.  This  should  help  you  understand  the 
instructions  and  addressing  types  that  are  new  to  the  68030. 
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The  Program  Model 
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The  illustration  shows  all  the  registers  of  the  68030.  Those  under  the 
heading  'User  Mode  Program  Model'  are  identical  to  those  of  the  68000: 
eight  each  of  the  universal  data  and  address  registers  (A7  is  the  stack 
pointer),  the  Program  Counter  and  the  Condition  Code  Register.  These 
are  the  only  registers  that  can  be  referenced  in  user  mode. 

Some  new  registers  have  been  added  for  supervisor  mode.  The  68000 
had  two  stack  pointers,  the  User  Stack  Pointer  (USP,  A7)  and  the 
Supervisor  Stack  Pointer  (SSP,  A7').  In  the  68030  the  latter  has  been 
further  divided  into  an  Interrupt  Stack  Pointer  (ISP,  A7')  and  a  Master 
Stack  Pointer  (MSP,  A"). 


The  following  registers  are  new  in  the  68030: 


VBR 

SFC 
DFC 


Vector  Base  Register:  With  this  register  the  base  address 
of  the  Exception  Vector  Table  can  be  set  to  any  desired 
value  (in  the  68000  this  was  always  0). 

Alternate  Function  Code  Registers 

SFC  and  DFC  stand  for  Source  and  Destination  Func- 
tion Code,  respectively.  These  registers  permit  explicit 
selection  of  the  address  region  to  be  accessed  by  a 
MOVE  instruction. 


CACR 
CAAR 


Five  address  regions  are  distinguished:  User  Program, 
Supervisor  Program,  User  Data,  Supervisor  Data  and 
Processor  (the  Processor  address  region  is  used  for 
communication  with  the  coprocessor  and  hardware,  for 
example  in  fetching  interrupt  vectors,  etc.). 

Data  can  be  easily  copied  between  the  various  address 
regions  by  means  of  MOVE  instructions  using  the 
Alternate  Function  Code  Registers. 

Cache  Control  Register 

Cache  Address  Register 

The  previous  two  registers  control  the  functioning  of 
the  integrated  data  and  address  caches. 
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CRP 

SRP 

TC 

TTO 

Til 

MMUSR 

SR 


CPU  Root  Pointer 

Supervisor  Root  Pointer 

Translation  Control  Register 

Transparent  Translation  Register  0 

Transparent  Translation  Register  1 

MMU  Status  Register 

The  previous  six  registers  belong  to  the  MMU. 

Status  Register 


USER  BYTE 
SYSTEM  BYTE     (CONDITION  CODE 
REGISTER) 

15   14  13  12  11   10   9     87654321     0 


T1 


TRACE 
ENABLE 

SUPERVISOR/USER 
STATE 

MASTER/INTERRUPT 
STATE 


TO 


M 


0    0 


INTERRUPT 
PRIORITY  MASK 


CARRY 

OVERFLOW 

ZERO 

NEGATIVE 

EXTEND 


The  Status  Register 

The  lower  byte  of  this  register  contains  the  condition  code  and  is 
therefore  referred  to  as  the  Condition  Code  Register  (CCR).  The  CCR 
can  be  referenced  in  user  as  well  as  supervisor  mode.  The  upper  half  of 
the  Status  Register,  the  System  Byte,  contains  important  system  flags: 

Interrupt  Priority  Mask 

Like  the  68000,  the  68030  distinguishes  even  interrupt  levels  by  priority, 
from  a  lowest  priority  of  1  to  a  highest  of  7. 

By  means  of  the  three  bits  in  the  Interrupt  Priority  Mask,  all  interrupts  up 
to  and  including  a  certain  priority  can  be  disabled.  Only  interrupts  of 
priority  higher  than  the  number  in  the  mask  will  be  executed.  Level  7  is 
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an  exception.  An  interrupt  of  this  priority  is  referred  to  as  a  Non- 
Maskable-Interrupt  (NMI)  and  cannot  be  disabled. 

Trace  Enable 

These  two  bits  control  the  processor's  trace  mode  (see  Exceptions). 

Supervisor  Bit 

When  this  bit  is  set,  the  68030  is  in  supervisor  as  opposed  to  user  mode. 
From  within  user  mode  this  bit  can  be  set  only  by  an  exception,  since 
direct  access  to  the  Status  Register's  System  Byte  is  not  permitted  in  user 
mode. 

Master  Bit 

The  Master  Bit  distinguishes  between  the  two  supervisor  stack  pointers. 
If  this  bit  is  NULL,  the  CPU  uses  the  Interrupt  Stack  Pointer.  If  it  is  set, 
the  CPU  uses  the  Master  Stack  Pointer  for  all  operations,  provided  that 
the  Supervisor  Bit  is  also  set,  and  switches  to  the  ISP  only  with  an 
interrupt. 


CCR 


The  Condition  Code  Byte  is  the  lower  half  of  the  Status 
Register.  It  contains  the  following  five  flag  bits: 


Carry 
Overflow 
Zero 
Negative 

Extend 


Carry  from  the  MSB  (most  significant,  or  last,  bit) 

Carry  from  the  next  to  last  bit 

Result  equals  zero 

Result  is  negative  (MSB  =  1) 

Like  Carry,  but  only  set  in  arithmetic  operations 


Every  instruction  that  alters  data  sets  these  flags  according  to  the  result. 
These  bits  can  be  used  as  decision  criteria  for  instructions  that  control 
program  flow,  as  in  the  Bcc  (Branch  on  condition  code)  instruction. 
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Bit  (0<Modulo  (Offset)<31,  Offset  of  0=MSB) 
31     30    29 


Byte 

31 


24     23  16      15 8     7 
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Data  Types 

The  fundamental  data  type  of  the  680xx  is  the  integer  number.  It  can 
have  a  size  of  8  bits  (one  byte),  16  bits  (one  word)  or  32  bits  (one  long 
word).  When  placed  in  a  data  register  (32  bits),  an  8-  or  16-bit  operand  is 
loaded  into  the  lower  half  or  quarter  of  the  register. 

Address  registers  can  contain  only  word  or  longword  data  types.  A  16- 
bit  value  written  to  an  address  register  is  expanded  to  32  bits  based  on 
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Unlike  the  68000,  the  68030  can  reference  all  data  types  on  byte 
addresses.  It  is  no  longer  necessary  to  align  a  word  or  longword  operand 
to  an  address  that  corresponds  to  a  multiple  of  its  size.  Nevertheless,  it  is 
always  faster  to  align  data  fields  by  the  number  of  bytes  they  occupy.  In 
a  hardware  sense,  the  68030  always  reads  one  long  word  at  a  time  (a 
transfer  of  32  bits  per  bus  cycle  over  the  32-bit  data  bus).  The  data  bus  is 
aligned,  however,  according  to  longword  addresses.  Two  bus  cycles  are 
thus  required  to  read  a  long  word  that  begins  on  an  odd  word  address 
(an  address  that  is  not  a  multiple  of  four). 

Aligned: 


ByteO     Bytel            Byte2     Byte3    Byte4            Byte5    Bvte6  Bvte7 

WordO 

Word2 
LongwordO 

WorcW 

Word6 

Longword4 

__ 

Misaligned: 

ByteO    Bytel     Byte2            Byte3    Byte4       Byte5             Byte6  Bvte7 

- 

Wordl 

Word3 
Longwordl 

~~ 

WordS- 

Word? 
Longword5 

.. 

Therefore,  although  it  is  possible  to  work  with  misaligned  data  on  the 
68030,  a  trade-off  in  terms  of  reduced  speed  will  likely  result. 

In  addition  to  the  integral  data  type  there  is  also  the  bit.  A  bit  can  be 
read,  set  or  cleared.  An  individual  bit  is  referenced  either  by  its  byte 
address  and  bit  number  (0  through  7)  or,  when  it  is  in  a  register  rather 
than  in  memory,  by  the  register  name  and  bit  number  (here  0  through  31). 
The  least  significant  bit  is  numbered  0. 

As  an  extension  of  the  bit  data  type,  the  bit  field  was  introduced  with  the 
68030.  The  bit  field  is  a  sequence  of  up  to  32  bits,  that  don't  have  to 
begin  on  a  byte  boundary.  Besides  a  memory  address  or  register  name,  an 
offset  is  required  to  reference  such  a  field.  It  indicates  the  beginning  of 
the  bit  field  relative  to  the  most  significant  bit  of  the  address  or  register. 
The  offset  is  a  signed  quantity,  meaning  that  the  field  can  also  begin 
before  the  base  address. 

The  size  of  the  bit  field  can  be  from  one  to  32  bits.  Within  the  field,  bits 
are  numbered  in  the  opposite  direction  from  that  of  integral  numbers.  Bit 
number  0,  whose  position  is  determined  by  the  offset,  is  the  most 
significant  bit  of  the  field. 
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A  new  integer  data  type  called  the  quad  word  has  been  added.  This  is 
simply  a  double  long  word  (64  bits).  Since  registers  are  32  bits,  two  of 
them  are  required  for  a  quad  word. 

The  quad  word  is  used  only  in  multiplication  and  division.  It  cannot  be 
simply  used  in  place  of  the  other  integer  types.  By  means  of  the  MOVEM 
instruction,  however,  it  is  possible  to  move  a  quad  word  between 
registers  and  memory.  (Naturally,  this  is  done  in  two  normal  MOVE! 
instructions.) 

One  last  data  type  exists,  the  binary  coded  decimal  (BCD)  numbers.  A 
BCD  number  is  stored  in  the  base-ten  system,  using  only  values  between 
0  and  9.  The  68030  distinguishes  between  packed  and  unpacked  BCD 
values.  In  unpacked  format,  one  byte  contains  one  digit;  the  upper  four 
bits  are  always  null.  In  packed  format,  both  half-bytes  (nibbles)  are  used. 

Types  of  Addressing 

Addressing  capabilities  are  greatly  expanded  in  the  68030  as  compared 
to  the  68000,  although  the  traditional  types  of  addressing  are  still  the 
most  frequently  used. 

Register  Direct 

The  desired  operand  is  the  register  itself. 

Syntax:         Rn 

(Rn  is  any  address  or  data  register  number) 

Absolute:      The  operand  address  is  given  immediately  after  the 
instruction. 

Syntax:         Address.W  or  Address! 


Immediate: 


(With  the  Address.W  (Address.Word)  format,  the  address  is 
expanded  to  32  bits  based  on  the  sign  of  the  16-bit  word 
value,  thus  referencing  only  the  first  or  last  32K  of 
memory.) 

The  byte,  word  or  long  word  following  the  instruction  is 
the  operand. 
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Syntax:         #Operand 

Address  Register  Indirect: 

The  value  in  the  given  register  contains  the  address  of  the 
operand  in  memory. 

Syntax:         (An) 

(An  is  any  address  register  number) 

Address  Register  Indirect  with  Postincrement  or  Predecrement: 

In  postincrement  addressing,  the  address  of  the  operand  in 
the  corresponding  register  is  incremented  by  the  size  of  the 
operand  in  bytes.  This  takes  place  AFTER  the  operand  has 
been  processed. 

In  predecrement  addressing,  the  address  is  decremented  by 
the  size  of  the  operand  BEFORE  the  instruction  is 
executed.  Thus  the  address  is  incremented  or  decremented 
by  one  for  byte,  two  for  word  and  four  for  longword 
operands.  (When  this  type  of  addressing  is  used  for 
coprocessor  data  types,  this  value  depends  on  their  size.) 

Syntax:         (An)+  (Postincrement) 
-(An)  (Predecrement) 

Address  Register  Indirect  with  Displacement: 

A  value  specified  with  the  instruction  (the  displacement)  is 
added  to  the  memory  address  from  the  address  register.  The 
result  is  the  operand  address  in  memory. 

Since  the  displacement  is  a  signed  16-bit  number,  this 
addressing  method  spans  an  area  of  32K  before  and  after 
the  address  contained  in  the  register. 

Syntax:         (di6,An) 

(dig  -  16-bit  displacement) 

Address  Register  Indirect  with  Index  and  8-bit  Displacement: 

This  method  is  slightly  more  complicated.  First  the 
displacement  is  added  to  the  value  in  the  address  register. 
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Then  the  CPU  multiplies  the  index,  which  may  be  in  any 
address  or  data  register,  by  a  factor  of  1,  2,  4  or  8,  and 
finally  adds  the  two  results. 


Value  from  Address  Register 

Displacement 

Value  from  Index  Register  (.W,.L)  *  1 , 2, 4  or  8 

Address  of  Operand 


Syntax:         (ds,An,Rn.SIZE  *  SCALE) 

(Rn.SIZE  *  SCALE  -  any  register  number  with  SIZE  of  16 
or  32  bits,  multiplied  by  SCALE  value  of  1,2,4  or  8.) 

Address  Register  Indirect  with  Index  and  Base  Displacement: 

This  method  of  addressing  closely  resembles  the  previous 
one,  except  that  the  displacement  may  be  16  or  32  bits. 
Also,  some  elements  may  be  left  out.  Address  register,  base 
displacement  and  index  register  are  optional.  If  the  address 
register  and  displacement  are  omitted,  for  example,  and  a 
data  register  is  used  as  the  index  register,  the  result  is  data 
register  indirect  addressing,  which  is  normally  not  available. 

Syntax:         (Bd.An.Rn.SIZE  *  SCALE) 
(Bd  -  base  displacement) 

Memory  Indirect  with  Postindex: 

Also  new  with  the  68030  are  the  memory  indirect  modes. 
These  methods  first  compute  an  address  in  memory,  from 
which  an  operand  address  is  then  read.  In  this  case  there 
are  two  displacements:  the  base  displacement  and  the  outer 
displacement.  The  former  is  added  to  the  address  register  in 
computing  the  memory  address,  the  latter  is  added  to  the 
operand  address.  The  index  register  is  likewise  added  to  the 
operand  address  after  multiplication  by  a  scaling  value  as 
described  earlier.  This  is  why  the  term  postindex  is  used. 

This  method  can  also  omit  certain  elements,  and  the  CPU 
will  assume  them  to  be  zeros. 
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Value  from  Address  Register 
Base  Displacement 
Memory  Address 

Value  from  above  Memory  Address 

Value  from  Index  Register  (.W,.L)  *  1 , 2, 4  or  8 

Outer  Displacement 

Operand  Address 


Syntax: 


([Bd,An],Rn.SIZE*SCALE,Od) 

(Bd  -  base  displacement,  Od  -  outer  displacement) 

The  square  brackets  indicate  the  memory  address  from 
which  the  operand  address  is  read. 


Memory  Indirect  with  Preindex: 

This  method  is  identical  to  the  above,  except  that  the  index 
is  added  to  the  address  register  instead  of  the  operand 
address. 


Value  from  Address  Register 

Value  from  Index  Register  (.W,.L)  *  1 ,2,4  or  8 

Base  Displacement 

Memory  Address 

Value  from  above  Memory  Address 
Outer  Displacement 
Operand  Address 


Syntax: 


([Bd,An,Rn.SIZE*SCALE],Od) 


PC-relative  Addressing: 

The  following  addressing  methods  can  use  the  Program 
Counter  (PC)  instead  of  an  address  register  as  a  base  value: 

•  indirect  with  displacement 

•  indirect  with  index  and  8-bit  displacement 

•  indirect  with  index  and  base-displacement 

•  memory  indirect  with  postindex 

•  memory  indirect  with  preindex 
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All  access  then  takes  place  not  in  the  User  or  Supervisor 
Data  region  but  in  the  corresponding  Program  region. 
These  addressing  methods  are  thus  suited  mainly  for  quick 
reference  to  nonvariable  data,  for  example  constants,  which 
reside  with  the  program  in  the  code  segment  (see  Operating 
System).  PC-relative  memory  access  always  refers  to  data 
that  resides  a  certain  distance  from  the  current  instruction, 
independent  of  the  instruction's  memory  address. 

Instructions 

The  majority  of  instructions  for  the  68030  are  those  that  applied  to  the 
68000,  with  some  enhancement  of  addressing  capabilities  or  additional 
data  types.  For  example,  two  long  words  can  be  multiplied  to  produce  a 
quad  word  as  the  result. 

New  instructions  are  the  bit  field  operations,  some  system  control 
instructions,  multiprocessor  instructions  and,  of  course,  the  cache, 
coprocessor  and  MMU  commands. 
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Data  Transfer  Instructions 


Instruction 

Syntax 

Size 

Comments 

EXG 

Rn.Rn 

32 

Rn  <-  ->Rn 

LEA 

<ea>,An 

32 

<ea>  ->  An 

LINK 

An,<d> 

16,32 

Sp  -  4  ->  Sp:  An  ->  (SP): 
SP  ->atw12  An,  SP  +  D  ->  SP 

MOVE 

<ea>,<ea> 

8,16,32 

source  ->  dest 

MOVEA 

<ea>,An 

16,32->32 

MOVEM 

list,<ea> 

16,32 

Register  list  ->  dest 

<ea>,list 

16,32 ->  32 

source  ->  Register  list 

MOVEP 

Dn,(d16,An) 

16,32 

Dn(31:24)->(An  +  d): 
Dn(23:16)->An  +  d+2: 
Dn(15:8)->(An  +  d  +  4): 
Dn(7:0)  ->  (An  +  d  +  6) 

(d16,An),Dn 

(An+d)->Dn(31:24): 
(An+d+2)->Dn(23:16): 
(An  +  d  +  4)->Dn(15:8): 
(An  +  d  +  6)  ->  Dn(7:0) 

MOVEQ 

#<data>,Dn 

8->32 

direct  data  ->  dest 

PEA 

<ea> 

32 

SP-4  ->  SP:  <ea>  ->  (SP) 

UNLK 

An 

32 

An  ->  SP:  (SP)  ->  An: 
SP  +  4  ->  SP 

Remarks: 


The  MOVEP  instruction  (Move  Peripheral)  transfers  data  between 
the  processor  and  peripheral  components  having  only  an  8-bit  data 
bus.  Although  it  isn't  needed  on  the  68030,  this  instruction  is 
retained  for  compatibility  with  the  68000. 

In  the  68000  with  its  16-bit  bus  width,  two  consecutive  byte 
registers  occupy  consecutive  word,  not  byte,  addresses.  This  means 
that  alternate  bytes  are  unused.  Four  MOVE.B  instructions  are 
required  to  move  a  long  word  into  as  many  consecutive  registers. 
MOVEP  increments  the  address  to  the  next  word  with  each  byte 
and  skips  over  the  gaps.  Thus  a  word  or  long  word  can  be  written 
to  consecutive  registers  with  a  single  instruction. 

The  68030's  bus  width  is  dynamic.  With  every  bus  cycle  it 
determines  whether  the  address  it  is  about  to  access  is  8,  16,  or  32 
bits  long.  Thus  even  8-bit  chip  registers  have  consecutive  addresses 
in  memory. 

<data>  in  MOVEQ  (Move  Quick)  represents  an  8-bit  value;  this  is 
expanded  to  32  bits. 
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Arithmetic  Operations 

All  arithmetic  operations  work  with  signed  integers.  ADDX,  SUBX  and 
NEGX  computations  include  the  X-Flag.  By  multiple  executions  of  these 
instructions,  computations  can  be  performed  on  numbers  larger  than  one 
long  word. 


Instruction 

Syntax 

Size 

Comments 

ADD 

Dn,<ea> 

8,16,32 

source+dest  ->  dest 

<ea>,Dn 

8,16,32 

ADDA 

<ea>,Dn 

16,32 

ADDI 

#<data>,<ea> 

8,16,32 

direct  data  +  dest  ->  dest 

ADDQ             i 

#<data>,<ea> 

8,16,32 

ADDX 

Dn,Dn 

8,16,32 

source  +  dest  +  X  ->  dest 

-(An).-(An) 

8,16,32 

CLR 

<ea> 

8,16,32 

0  ->  dest 

CMP 

<ea>,Dn 

8,16,32 

dest  -  source 

CMPA 

<ea>,An 

16,32 

CMPI 

#<data>,<ea> 

8,16,32 

dest  -  direct  data 

CMPM 

(An)+,(An)+ 

8,16,32 

dest  -  source 

CMP2 

<ea>,Rn 

8,16,32 

DIVS/DIVU 

<ea>,Dn 

32/16 ->  16:16 

dest/source  ->  dest  (with  or 
without  sign) 

<ea>,Dr:Dq 

64/32  ->  32:32 

<ea>,Dq 

32/32  ->  32 

DIVSL7DIVUL 

<ea>,Dr:Dq 

32/32  ->  32:32 

EXT 

Dn 

8->  16 

with  sign  extended  dest  -> 
dest 

Dn 

16->32 

EXTB 

Dn 

8->32 

MULS/MULU 

<ea>,Dn 

16x16->32 

source  x  dest  ->  dest  (with 
or  without  sign) 

<ea>,DI 

32  x  32  ->  32 

<ea>,Dh:DI 

32  x  32  ->  64 

NEG 

<ea> 

8,16,32 

0  -  dest  ->  dest 

NEGX 

<ea> 

8,16,32 

0  -  dest  -  X  ->  dest 

SUB 

<ea>,Dn 

8,16,32 

dest  -  source  ->  dest 

Dn,<ea> 

8,16,32 

SUBA 

<ea>,An 

16,32 

SUBI 

#<data>,<ea> 

8,16,32 

dest  -  direct  data  ->  dest 

SUBQ 

#<data>,<ea> 

8,16,32 

SUBX 

Dn,Dn 

8,16,32 

dest  -  source  -  X  ->  dest 

-(An).-(An) 

8,16,32 

Remarks: 


<data>  in  SUBQ  and  ADDQ  must  be  0  through  7. 
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•  In  multiplication  and  division  (MUL,  DIV)  quad  words  can  also  be 
used  (64  bits).  In  this  case,  two  data  registers  are  declared  instead  of 
one. 

Logical  Operations 

These  instructions  perform  the  logical  linking  functions  (And,  Or, 
Exclusive-or  and  Negation). 

The  TST  instruction  subtracts  0  from  an  operand  and  sets  the  appropriate 
condition  codes  in  the  Status  Register.  This  can  be  used  to  test  a  value  in 
memory  for  zero. 


Instruction 

Syntax 

Size 

Comments 

AND 

<ea>,Dn 

8,16,32 

source  /  dest  ->  dest 

Dn,<ea> 

8,16,32 

ANDI 

#<data>,<ea> 

8,16,32 

Data  /  dest  ->  dest 

EOR 

Dn,<data>  <ea> 

8,16,32 

source  EOR  dest  ->  dest 

EORI 

#<data>,<ea> 

8,16,32 

Data  EOR  dest  ->  dest 

NOT 

<ea> 

8,16,32 

dest  ->  dest 

OR 

<ea>,Dn 

8,16,32 

source  OR  dest  ->  dest 

Dn,<ea> 

8,16,32 

ORI 

#<data>,<ea> 

8,16,32 

Data  OR  dest  ->  dest 

TST 

<ea> 

8,16,32 

source  -  0  to  set  cond.codes 

Shift  and  Rotation  Instructions 

Shift  and  rotation  instructions  differ  in  whether  or  not  bits  displaced  from 
one  end  of  the  operand  are  brought  around  to  the  other.  ROXR  and 
ROXL  also  include  the  X-Bit  of  the  Status  Register  in  the  rotation. 

Shift  instructions  differ  with  regard  to  the  MSB.  In  the  arithmetic  shift 
instruction  it  is  interpreted  as  a  sign  and  retained  when  shifting  right, 
while  in  the  logical  variant  it  is  replaced  by  zero. 

When  shifting  left  there  is  no  difference  between  the  arithmetic  (ASL) 
and  the  logical  (LSL)  version  of  the  instruction. 

With  all  these  instructions  one  declares  the  number  of  bits  to  be  shifted, 
followed  by  a  data  register.  Permissible  values  are  1  through  8  with 
immediate  addressing  and  1  through  63  when  using  a  data  register. 

A  memory  location  can  also  be  shifted  directly,  but  only  as  a  word  and 
only  by  one  bit  at  a  time. 
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The  swap  instruction  switches  the  two  words  in  a  data  register. 


Operand  Syntax 


On,  On 

#  ((Jala),  On 

(ea) 


On.  Dn 

o  (data),  Dn 
(ea) 


Dn,  Dn 

* (data),  Dn 
(ea) 


Dn,  Dn 

*  (data),  Dn 
(ea) 


On,  Dn 

it  (data).  Dn 
(ea) 


Dn,  Dn 

ft  (data),  Dn 
(ea) 


Dn.  Dn 

s  (data).  Dn 
(ea) 


Dn,  Dn 

#  (data),  Dn 

(ea) 


Operand  Size 


S.  1G,  32 

8.  16,  32 

16 


8.  16.  32 

8,  16,  32 

16 


8,  16.  32 

8,  16,  32 

16 


8,  16,  32 

8,  16,  32 

16 


8.  16.  32 

8.  16,  32 


8.  16,  32 

8,  16,  32 

16 


8.  16.  32 
8.  16.  32 


8.  16.  32 

8.  16.  32 

16 


Operation 


\yuc\+-{~+- 


[-»!  ,  »  V*FZ\ 


Qi/c}*-[3E 


►i         »  h»f««l 


m^ 


>3 


^i 


iPMZI 


rrVn  «       i*-nrw 


L>nn-»r=^>L»rvi 


Imsw  I  LSW  I 

A    I 


Shift  and  Rotation  Instructions 

Bit  Data  Type  Instructions 

All  bit  manipulation  instructions  set  the  Zero-Flag  according  to  the 
condition  of  the  selected  bit.  Then  the  bit  is  either  cleared  (BCLR),  set 
(BSET)  or  inverted  (BCHG).  The  bit  number  can  be  declared  immediately 
or  in  a  data  register. 
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Instruction 

Operand 

Operand 

Operation 

Syntax 

Format/Size 

BCHG 

Dn,<ea> 

8,32 

-  <bit  number>  from  dest->Z- 
>bit  of  dest 

#<data>,<ea> 

8,32 

BCLR 

Dn,<ea> 

8,32 

-  <bit  number>  from  dest  ->Z; 

#<data>,<ea> 

8,32 

0->bit  of  dest 

BSET 

Dn,<ea> 

8,32 

-  <bit  number>  from  dest  ->Z; 

#<data>,<ea> 

8,32 

1  ->bit  of  dest 

BTST 

Dn,<ea> 

8,32 

-  <bit  numbeo  from  dest  ->Z 

#<data>,<ea> 

8,32 

Bitfield  Instructions 

The  bitfield  commands  transfer  the  MSB  of  the  field  to  the  N  flag  and  set 
the  Zero  flag  if  all  bits  of  the  field  are  null.  Then  the  corresponding 
operation  is  performed. 


Instruction 

Syntax 

Size 

Comments 

BFCHG 

<ea>  (offset:length) 

1-32 

Field  ->  Field 

BFCLR 

<ea>  (offset:length) 

1-32 

0->  Field 

BFEXTS 

<ea>  (offset:length),Dn 

1-32 

Field  ->  Dn  ;extend  sign 

BFEXTU 

<ea>  (offset:length),Dn 

1-32 

Field  ->  Dn  ;extend  unsign 
(zero) 

BFFFO 

<ea>  (offset:length),Dn 

1-32 

Searches  for  first  set  bit  in 
field;  offset  ->  Dn 

BFINS 

Dn,<ea>  (offset:length) 

1-32 

Dn  ->  Field 

BFSET 

<ea>  (offset:length) 

1-32 

1  ->  Field 

BFTST 

<ea>  (offset:length) 

1-32 

MSB  ->  N  (OR  all  )->  Z 

Binary  Coded  Decimal  (BCD)  Instructions 

ABCD,  SBCD  and  NBCD  execute  the  corresponding  arithmetic 
operations  with  packed  BCD  numbers.  Converting  between  packed  and 
unpacked  format  of  BCD  numbers  is  accomplished  by  using  the  PACK 
and  UNPACK  instructions. 
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Instruction 

Operand  Syntax 

Operand 
Size 

Operation 

ABCD 

Dn.Dn 

8 

sourcel  0-Klest1 0+X- 
>dest 

-(An).-(An) 

8 

NBCD 

<ea> 

8 

0-dest10-X->dest 

PACK 

(An).-(An) 

#<data> 

16->8 

Unpacked  source+Data- 
>packed  dest 

Dn,Dn#<data> 

16->8 

SBCD 

Dn.Dn 

8 

destl  0-source  1 OX  ~>dest 

-(An),(An) 

8 

UNPK 

(An).-(An) 

8->16 

packed  source- 
unpacked  source 

#<data> 

unpacked  source+data- 
>unpacked  source 

Dn,Dn,#<data>8->16 

Program  Flow  Control 


Instruction 

Operand  Syntax 

Operand 
Size 

Operation 

ABCD 

Dn.Dn 

8 

sourcel  04dest1 0+X- 
>dest 

-(An).-(An) 

8 

NBCD 

<ea> 

8 

0-dest10-X->dest 

PACK 

(An).-(An) 
#<data> 

16->8 

unpacked  source+data- 
>packed  dest 

Dn,Dn#<data> 

16->8 

SBCD 

Dn.Dn 

8 

destl  0-source1 0-X->dest 

-(An),(An) 

8 

UNPK 

(An)(-(An) 

8->16 

packed  source- 
>unpacked  source 

#<data> 

unpacked  source+data- 
>unpacked  source 

Dn,Dn,#<data>8->16 

Remarks: 


The  variable  'cc'  can  be  replaced  by  any  of  the  following  condition 
codes: 
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Code 

Condition 

T 

true  (not  used  with  Bcc) 

F 

false  (not  used  with  Bcc) 

HI 

higher,  logically 

LS 

lower  or  same,  logically 

CC(HS) 

C(arry)  flag  cleared,  logically  higher  or  same 

CS(LO) 

C(arry)  flag  set,  logically  lower 

NE 

not  equal,  Z(ero)  flag  cleared 

EQ 

equal,  Z(ero)  flag  set 

VC 

Overflow  clear,  V  flag  cleared 

VS 

Overflow  set,  V  flag  set 

PL 

Plus,  N(egative)  flag  cleared 

Ml 

Minus,  N(egative)  flag  set 

QE 

greater  or  equal,  arithmetically 

LT 

lower  than,  arithmetically 

GT 

greater  than,  arithmetically 

LE 

lower  or  equal,  arithmetically 

By  testing  the  flags  after  a  CMP  or  SUB  operation  (see  arithmetic 
instructions),  the  relationship  between  the  two  operands  can  be 
determined.  If,  for  example,  the  second  number  is  greater  than  the  first, 
the  condition  GT  will  be  true. 

Again  there  is  a  difference  between  logical  and  arithmetic  operations  in 
terms  of  the  sign.  Since,  for  example,  the  byte  $FF  can  stand  for  either  -1 
or  +255,  comparing  it  with  0  will  return  $FF  >  0  as  a  logical  condition 
(without  sign)  and  $FF  <  0  as  an  arithmetic  condition  (with  sign). 

In  other  instructions,  relational  statements,  such  as  greater  than,  are  not 
definitive.  Here  the  condition  codes  are  used  to  test  the  condition  of  an 
individual  bit.  For  example,  after  a  bitfield  instruction,  BEQ  checks 
whether  the  Zero  flag  was  set,  meaning  that  all  bits  in  the  field  were 
cleared,  instead  of  checking  for  equality. 

Therefore  both  meanings  are  given  in  the  above  table. 

RTD  fetches  a  return  address  from  the  stack  and  sets  the  stack 
pointer  to  the  value  of  <data>. 

•       RTR  fetches  another  word  from  the  stack  before  the  return  address 
and  writes  it  to  the  CCR. 
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System  Control  Instructions 

This  instruction  set  is  comprised  of  the  privileged  instructions 
(executable  only  in  supervisor  mode),  instructions  that  generate  Trap 
Exceptions  and  those  that  write  to  the  Condition  Code  Register  (CCR). 


Instruction 

Syntax 

Size 

Comments 

Privileged 

ANDI 

#<data>,SR 

16 

direct  data  AND  SR  -> 
SR 

EORI 

#<data>,SR 

16 

direct  data  EOR  SR  -> 
SR 

MOVE 

<ea>,SR 

16 

source  ->  SR 

SR,<ea> 

16 

SR  ->  dest 

MOVE 

USP.An 

32 

USP  ->  An 

An.USP 

32 

An  ->  USP 

MOVEC 

Rc,Rn 

32 

Re  ->  Rn 

Rn.Rc 

32 

Rn  ->  Re 

MOVES 

Rn,<ea> 

8,16,32 

Rn  ->  dest  with  DFC 

<ea>,Rn 

source  with  SFC  ->  Rn 

ORI 

#<data>,SR 

16 

direct  data  V  SR  ->  SR 

RESET 

none 

none 

RTE 

none 

none 

(SP)  ->  SR;  SP  +  2;  (SP) 
->  PC;  SP  +  4  ->  SP; 

STOP 

#<data> 

TRAP  Generating 

16 

direct  data  ->  SR 

BKPT 

#<data> 

none 

CHK 

<ea>,Dn 

16,32 

if  Dn  <  0  or  Dn  >  (ea), 
CHK  is  called 

CHK2 

<ea>,Rn 

8,16,32 

ILLEGAL 

none 

none 

SSP  -  2  ->  SSP;  vector 

offset  ->  (SSP) 

SSP  -  4  ->  SSP;  PC  -> 

(SSP); 

SSP  -  2  ->  SSP;  SR  -> 

(SSP); 

vector  address  of  illegal 

instruction  ->  PC 

TRAP 

#<data> 

none 

SSP  -  2  ->  SSP; 
SSP  -  4  ->  SSP;  PC  -> 
(SSP);  SSP  -  2  ->  SSP; 
SR  ->  (SSP);  vector 
address  ->  PC 

TRAPcc 

none 

none 

executes  TRAP  if  cc  is 
true 

#<data> 

16,32 

TRAPV 

none 

Condition  Code  Register 

none 

ANDI 

#<data>,CCR 

8 

direct  data  AND  CCR  -> 
CCR 
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Instruction 

Syntax 

Size 

Comments 

EORI 

#<data>,CCR 

8 

direct  data  EOR  CCR  -> 
CCR 

MOVE 

<ea>,CCR 

16 

source  ->  CCR 

CCR,<ea> 

16 

CCR  ->  dest 

ORI 

#<data>,CCR 

8 

direct  data  V  CCR  -> 
CCR 

Multiprocessor  Instructions 

Multiprocessor  instructions  are  all  those  that  carry  out  a  Read-Modify- 
Write  bus  cycle.  What  does  this  mean? 

In  a  multiprocessor  system  (e.g.,  the  Amiga  with  a  PC/AT  expansion 
card),  CPUs  running  in  parallel  can  access  the  same  memory  region.  Let's 
assume  there  is  a  common  data  structure  in  which  only  one  processor  is 
allowed  to  work  at  any  given  time.  Each  CPU  has  a  place  in  memory 
where  it  signals  its  activity  to  the  other.  This  is  done  by  means  of  the  IBD 
bit  (Ich  bin  dran,  German  for  'I  am  here').  In  preparing  to  access  the  data 
structure  in  question,  CPU  A  has  just  read  CPU  B's  IBD  bit  and,  seeing 
that  it  is  free,  is  about  to  set  its  own  bit  on.  At  this  time,  CPU  B  makes  the 
same  check  and  also  concludes  that  the  data  structure  is  available  for 
access.  The  result  is  conflicting  access  by  both  CPUs. 

There  are  software  solutions  for  the  mutual  access  exclusion  problem, 
but  the  68030  offers  a  faster  and  simpler  one  in  its  hardware.  During  a 
Read-Modify- Write  cycle,  it  signals  the  hardware  that  controls  RAM  that 
this  process  may  not  be  interrupted.  Thus  CPU  A  can  complete  its  setting 
of  the  IBD  bit  before  CPU  B  is  allowed  to  check  it. 


Instruction 

Operand  Syntax 

Operand 

Operation 

Read-Modify-Write 

Size 

CAS 

Dc,Du,<ea> 

8,16,32 

dest-Dc->CC; 

If  Z  is  set.,  then  Du->dest 

else  dest->Dc 

CAS2 

Dc1:Dc2 

,Du1:Du2 

,(Rn):(Rn) 

8,16,32 

two  operands  CAS 

TAS 

<ea> 

8 

dest-0,  set  cond.codes; 
1->dest(7)  Coprocessor 

cpBcc 

<Label> 

16,32 

If  cpcc  true,  then  pc+D->PC 

cpDBcc 

<Label>,Dn 

16 

If  cpcc  false,  then  Dn-1->Dn 
If  Dn  <>  1 ,  then  PC+d->PC 

cpGEN 

user  def. 

user  def. 

operand->coprocessor 

cpRESTORE 

<ea> 

none 

Restore  coprocessor  status 
from  <ea> 
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Instruction 

Operand  Syntax 
Read-Modify-Write 

Operand 
Size 

Operation 

cpSAVE 

<ea> 

none 

Save  coprocessor  status 
to<ea> 

cpScc 

<ea> 

8 

If  cpcc  true,  then  1's->dest, 
else  0's->dest 

cpTRAPcc 

none 
#<data> 

none 

16,32 

If  cpcc  true,  then  generate 
TRAPcc  Exception 

Exceptions 

With  an  exception  the  processor  interrupts  the  currently  executing 
program  and  jumps  to  a  routine  that  handles  the  error  or  carries  out  the 
desired  action.  An  exception  on  the  68030,  then,  includes  anything  that 
interrupts  normal  program  execution:  reset,  interrupts,  software  errors, 
bus  errors,  etc. 

Exception  handling  takes  place  in  several  steps: 

1.  First  the  CPU  makes  an  internal  copy  of  the  Status  Register.  Then 
the  Supervisor  Bit  is  set,  the  Trace  Bits  cleared  and,  if  the  exception 
was  an  interrupt,  the  Interrupt  Priority  Mask  adjusted. 

2.  Now  the  vector  number  is  ascertained,  which  depending  on  the 
exception  type,  is  either  already  provided  or  must  be  read  over  the 
bus  (interrupts,  coprocessor). 

3.  With  a  Reset  (which  also  is  considered  an  exception),  the  processor 
saves  its  current  internal  position  on  the  stack,  so  that  the 
interrupted  program  can  resume  after  exception  processing.  With  an 
interrupt,  if  the  Master  bit  is  set,  the  CPU  clears  it  and  rewrites  the 
information  to  the  stack.  However,  this  time  it's  written  to  the 
Interrupt  Stack  (ISP)  rather  than  the  Master  Stack  (MSP). 

The  exact  format  of  the  stack  data  varies  greatly  among  the  various 
exception  types.  Always  present  are  the  vector  offset,  the  old  value 
of  the  Program  Counter,  and  the  Status  Register  (saved  initially). 

4.  In  the  final  step,  the  processor  reads  the  exception  routine  address 
from  the  vector  table  and  begins  its  execution.  The  remainder  of  the 
exception  handling  is  then  accomplished  by  the  software. 
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Vector  Number(n) 

Vector  Offset  Hex 

Meaning 

0 

000 

Interrupt  Stack  Pointer  after  Reset 

1 

004 

Program  Counter  (PC)  after  Reset 

2 

008 

Bus  error 

3 

OOC 

Address  error 

4 

010 

Illegal  instruction 

5 

014 

Division  by  zero 

6 

018 

CHK-,  CHK2-instruction 

7 

01C 

cpTRAPcc-,  TRAPcc-,  TRAPV- 
instruction 

8 

020 

Privilege  violation 

9 

024 

Single  step  (Trace) 

10 

028 

Line  1010  emulation 

11 

02C 

Line  1111  emulation 

12 

030 

Reserved  (not  used) 

13 

034 

Coprocessor  protocol  violation 

14 

038 

Format  error 

15 

03C 

Uninitialized  interrupt 

16 

040 

through 

Reserved 

23 

05C 

24 

060 

Spurious  interrupt 

25 

064 

Level  1  interrupt  autovector 

26 

068 

Level  2  interrupt  autovector 

27 

06C 

Level  3  interrupt  autovector 

28 

070 

Level  4  interrupt  autovector 

29 

074 

Level  5  interrupt  autovector 

30 

078 

Level  6  interrupt  autovector 

31 

07C 

Level  7  interrupt  autovector 

32 

080 

through 

TRAP  0-15 
instruction  vectors 

47 

0BC 

48 

OCO 

FPCP-branching  or  Set  by 
unregulated  condition 

49 

0C4 

FPCP  Inexact  result 

50 

0C8 

FPCP  Division  by  zero 

51 

OCC 

FPCP  Underflow 

52 

0D0 

FPCP  Operations  error 

53 

0D4 

FPCP  Overflow 

54 

0D8 

FPCP  Signaled  NAN 

55 

0DC 

Reserved 

56 

0E0 

MMU  setting  error 

57 

0E4 

Provided  for  MC68851  (not  used 
in  MC68030) 

58 

0E8 

Provided  for  MC68851  (not  used 
in  MC68030) 

59 

OEC 

through 

Reserved 

63 

OFC 
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Vector  Number(n)        Vector  Offset  Hex      Meaning 


64 

100 

through 

User-defined 

vectors 

255 

3FC 

Every  exception  is  assigned  a  specific  vector,  except  for  interrupts, 
whose  vectors  are  generated  as  required  by  the  appropriate  hardware. 
All  vectors  consist  of  a  long  word  with  the  address  of  the  appropriate 
exception  handler.  The  Exception  Vector  Table  has  256  entries,  thus  a 
size  of  IK.  Its  address  in  memory  can  be  determined  by  the  Vector  Base 
Register.  After  a  reset  it  will  be  at  address  0,  the  beginning  of  system 
memory. 

Exception  Types 

Reset,  Vectors  O&l 

Reset  is  the  only  exception  that  does  not  permit  resumption  of  the  old 
program.  The  processor  clears  all  internal  registers  without  saving 
anything  on  the  stack,  and  the  caches  and  MMU  are  shut  off.  In  the 
Status  Register,  the  Supervisor  Bit  is  set  and  the  Interrupt  Mask  set  to  7. 
It  then  begins  program  execution  at  the  address  in  Vector  1.  Vector  0  is 
written  to  the  ISP  as  initialization  value. 

Bus  Error,  Vector  2 

If  a  bus  access  cannot  proceed  because  of  error,  for  example,  when  an 
attempt  is  made  to  write  to  ROM,  the  hardware  can  inform  the  CPU  by 
signaling  a  bus  error.  All  processors  of  the  680x0  family  have  the  /BERR 
line  for  this  purpose. 

In  the  Amiga,  a  bus  error  is  caused  only  by  expansion  cards  claiming  the 
same  or  illegal  addresses. 

Address  Error,  Vector  3 

An  address  error  results  when  an  instruction  that  must  be  at  an  even 
address  is  read  at  an  odd  address.  This  occurs  much  more  frequently  on 
the  68000,  since  there  access  of  words  and  long  words  is  also  forbidden 
at  odd  addresses. 
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Illegal  Instruction,  Vector  4 

Line- A-  and  Line-F-emulator,  Vectors  10  &  1 1 

These  exceptions  are  assigned  to  the  various  bit  patterns  that  do  not 
represent  a  valid  instruction  (words  with  hexadecimal  A  ($Axxx)  in  the 
upper  four  bits,  those  with  F  ($Fxxx),  and  other  illegal  bit  patterns. 

Line-A-emulation  can  be  used  to  implement  proprietary  instructions, 
which  can  then  be  executed  over  the  exception  handler.  Distinguishing 
among  various  functions  is  done  by  means  of  the  lower  12  bits. 

Line  F  distinguishes  whether  bits  9  through  1 1  of  the  instruction  word 
are  unequal  to  zero.  This  indicates  a  coprocessor  instruction.  Only  when 
this  is  not  the  case,  that  is,  the  hardware  signals  a  bus  error  in  accessing 
the  instruction,  does  an  F-line  exception  occur.  Otherwise  the 
coprocessor  executes  the  instruction. 

With  this  mechanism  it  is  possible  to  emulate  entire  coprocessor  functions 
via  software  in  the  exception  handler,  as  if  it  were  actually  present.  If  the 
FPU  is  present,  the  software  can  be  reused  without  change.  In  the 
A3000,  since  the  coprocessor  is  completely  integrated,  there  is  no  need 
to  worry  about  its  emulation. 

If  bits  9  through  1 1  equal  zero,  then,  depending  on  the  bit  pattern  in  the 
lower  half  of  the  instruction  word,  either  it  is  a  valid  MMU  instruction  or 
the  F-line  exception  occurs.  But  since  MMU  instructions  are  permitted 
only  in  supervisor  mode,  an  instruction  word  in  the  form  $F0xx  in  user 
mode  always  results  in  a  privilege  violation. 

Privilege  Violation,  Vector  8 

A  privilege  violation  occurs  when  one  of  the  following  instructions  is 
executed  in  user  mode: 

ANDI  to  SR,  EOR  to  SR,  FRESTORE,  FSAVE,  MOVE  from  SR,  MOVE  to 
SR,  MOVE  USP,  MOVEC,  MOVES,  ORI  to  SR,  PFLUSH,  PMOVE, 
PLOAD,  PTEST,  RESET,  RTE,  STOP 

These  instructions  apply  only  in  supervisor  mode.  Note:  The  instruction 
'MOVE  from  SR'  was  permitted  in  user  mode  on  the  68000.  On  the 
68030  it  is  permitted  only  in  supervisor  mode. 
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Zero  Divide,  Vector  5 

CHK  and  TRAP  Instructions,  Vectors  6  &  7 

Instruction  Trap  Exceptions  occur  with  the  corresponding  condition  in 
an  instruction.  They  are  intentional  and  signal  an  arithmetic  or  logical 
error  condition  in  the  program: 

•  Division  by  zero 

•  TRAPcc  instruction  with  valid  condition 
CHK  or  CHK2  detect  a  partition  overwrite 

Trace  Exception,  Vector  9 

The  68030  has  two  trace  modes  to  facilitate  debugging.  They  are 
selected  using  the  Trace  Bits  in  the  Status  Register: 


T1  TO        Trace  mode 


Trace  disabled 

Trace  every  transfer  of  control  (BRA,  JMP  etc.) 

Trace  every  instruction 

not  implemented 


Depending  on  the  selected  mode,  a  trace  exception  follows  every 
instruction  or  only  those  that  transfer  program  flow.  Within  the 
exception  handling  routines  the  trace  bits  are  set  to  zero  to  inhibit 

subsequent  trace  exceptions. 

Trace  mode  makes  it  possible  to  follow  the  execution  of  a  program  step 
by  step. 

Independent  of  the  mode  selected,  an  instruction  that  writes  to  the  Status 
Register  generates  a  trace  exception. 

Format  Error,  Vector  14 

The  68030  places  varying  numbers  of  words  on  the  stack  depending  on 
the  type  of  exception.  These  are  returned  from  the  stack  by  the  RTE 
instruction  (Return  from  Exception)  so  that  the  interrupted  program  can 
continue  processing.  A  format  error  exception  occurs  when  the 
processor  detects  an  illegal  stack  format  and  cannot  restore  the  previous 
state. 
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This  error  is  caused  by  programs  that  overwrite  stack  data. 

Interrupts 

A  number  of  vectors  are  assigned  to  interrupts:  the  spurious  interrupt 
vector,  24,  the  seven  autovectors,  25  -  31,  all  user-defined  vectors,  64  - 
255,  and  the  uninitialized  interrupt  vector,  15. 

As  was  previously  mentioned  in  the  discussion  of  the  Status  Register,  an 
interrupt  exception  is  called  only  when  the  interrupt  level  in  the  SR  is 
lower  than  that  of  the  signal  in  the  interrupt  entry.  If  this  is  the  case,  the 
68030  attempts  to  read  the  appropriate  interrupt  vector  over  the  data 
bus.  It  executes  for  this  purpose  an  Interrupt  Acknowledge  Cycle,  by 
which  the  hardware  detects  that  its  interrupt  request  has  been 
acknowledged  and  that  it  can  make  a  vector  available. 

Now  there  are  three  possibilities: 

•  The  hardware  delivers  a  vector  (in  the  range  of  64  -  255). 

•  It  signals  an  autovector  interrupt  with  one  of  the  seven  autovectors 
(25  -  31),  according  to  the  interrupt  level.  This  is  the  case  with  the 
Amiga. 

•  It  responds  with  a  bus  error  and  the  spurious  interrupt  (24)  occurs. 

The  Uninitialized  Interrupt  (15)  occurs  when  a  peripheral  chip  tries  to 
deliver  a  vector  that  has  not  yet  been  initialized  by  the  processor.  This 
vector  is  therefore  not  generated  by  the  processor,  but  rather  is  read  by 
the  Interrupt  Acknowledge  Cycle  when,  due  to  a  software  error,  the 
corresponding  vector  register  in  the  chip  that  produced  the  interrupt  has 
not  been  set. 


11.2.1        The  PMMU 


With  the  Paged  Memory  Management  Unit,  the  68030  provides 
hardware-controlled  memory  management  and  protection  for  the 
operating  system.  The  PMMU  supports  two  mechanisms  to  implement 
this  control: 

1.  The  generation  of  a  virtual  address  space  for  each  task. 

2.  The  validation  of  authorization  for  every  memory  access. 
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Virtual  Memory 

Formerly,  any  reference  to  address  locations  or  memory  in  the  Amiga 
referred  to  the  physical  memory,  that  is,  the  actual  RAM  chips.  In  earlier 
models  than  the  A3000,  every  address  transmitted  over  the  address  bus 
selects  one  precise  memory  location  in  the  corresponding  component. 
This  fixed  assignment  of  addresses  from  the  processor  to  the  various 
registers  and  memory  locations  is  inherent  in  the  hardware  and  normally 
cannot  be  changed.  Although  there  are  some  exceptions  to  this  rule  (e.g., 
bank  switching),  they  don't  apply  to  the  Amiga.  So,  for  every  address, 
there  is  only  one  memory  location. 

In  a  multitasking  operating  system,  where  two  or  more  tasks  can  run 
concurrently,  the  tasks  must  utilize  different  addresses  for  their  data. 
When  a  task  occupies  memory,  it  reduces  the  amount  available  to  all 
other  tasks.  Eventually  memory  becomes  so  fragmented  from  continuos 
allocation  and  de-allocation,  that  sufficient  contiguous  memory  for  even 
a  simple  function  is  no  longer  available. 

Without  the  PMMU,  logical  memory  (the  memory  addresses  used  by  the 
machine-language  instructions  of  the  various  tasks)  is  identical  to 
physical  memory. 

In  a  system  with  virtual  memory  management,  every  task  is  assigned  its 
own  logical  address  partition.  The  maximum  size  of  each  partition  is 
theoretically  the  entire  address  space,  or  4  Gigabytes  with  the  68030. 
This  logical  address  partition  does  not  exist  physically.  Each  task  has  4 
Gigabytes  of  memory,  but  only  in  a  "virtual"  sense.  A  specific  correlation 
must  be  established  between  physical  memory  (usually  only  1  Megabyte 
in  68030-based  computers)  and  the  logical  addresses  of  all  the  tasks.  The 
PMMU  does  just  that.  For  every  memory  access,  it  translates  the  logical 
address  to  the  appropriate  physical  address  and  also  validates  the  access 
authority  of  the  task  for  the  area  in  question. 

The  fundamental  unit  of  memory  on  which  these  mechanisms  operate  is 
called  a  page.  The  entire  logical  address  space  is  divided  into  equal-size 
pages  (page  size  may  be  as  small  as  256  bytes  or  as  large  32K).  A  logical 
page  can  be  mapped  to  a  physical  page  of  the  same  size.  Physical  pages 
in  memory  are  sometimes  referred  to  as  frames.  Of  course  not  all  logical 
pages  can  map  cumulatively  to  main  memory  frames,  since  the  virtual 
address  space  far  exceeds  the  physical.  This  fact  is  transparent,  though, 
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to  executing  tasks,  which  share  memory  without  even  "knowing"  it.  If  a 
task  requests  a  page  that  is  not  currently  in  memory,  the  MMTJ  detects 
this  condition,  called  a  page  fault,  and  generates  a  bus  error.  The 
operating  system  can  now  load  the  desired  page  to  an  available  frame  in 
RAM.  If  none  is  available,  a  page  can  be  swapped  to  disk  and 
temporarily  saved  to  make  room  for  the  new  logical  page,  and  the  fault 
can  be  satisfied. 

Besides  managing  the  transparent  sharing  of  memory  among  tasks,  the 
PMMU  also  solves  the  problem  of  memory  fragmentation.  Physically 
noncontiguous  available  fragments  can  be  allocated  by  the  PMMU  in 
such  a  way  as  to  logically  satisfy  a  task's  request  for  contiguous  address 
space. 

These  capabilities  are  not  implemented  in  the  current  version  of  the 
Amiga  operating  system.  However,  it  is  worthwhile  to  study  the 
functions  and  programming  of  the  processes  previously  described,  since 
the  PMMU  is  a  fixed  part  of  the  Amiga  3000  hardware.  Also,  virtual 
addressing  is  used  by  the  UNIX  operating  system,  which  Commodore 
also  offers  for  the  3000.  Finally,  a  knowledge  of  the  PMMU  will  allow 
you  to  experiment  with  your  own  applications. 

To  perform  the  translation  of  logical  into  physical  addresses,  the  PMMU 
naturally  needs  information  about  the  allocation  of  pages  requested  by 
the  operating  system.  A  multi-level  structure  called  a  translation  tree  is 
constructed  in  main  memory  for  this  purpose.  The  translation  tree 
indicates  whether  the  desired  logical  page  is  contained  in  a  physical  page ; 
frame  and  if  so,  which  one. 

If  the  tree  were  to  be  scanned  for  every  memory  access,  however,  the 
CPU  would  have  to  sacrifice  most  of  its  processing  power  for  this  task 
alone.  In  reality  the  PMMU  slows  program  execution  by  only  1  to  2%. 

The  solution  lies  again  in  a  cache:  the  ATC  (Address  Translation  Cache). 
Every  time  a  valid  allocation  is  read  from  the  translation  tree,  the  PMMU 
transfers  it  to  the  ATC.  The  ATC  has  room  for  up  to  22  entries.  Upon 
subsequent  request  for  any  of  these  pages,  the  cache  signals  their 
availability  to  the  PMMU.  As  long  as  a  time-consuming  table  search  is 
avoided,  memory  access  with  PMMU  address  translation  is  just  as  fast  as 
without  it. 
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Only  when  a  program  references  a  page  for  the  first  time  or  when  more 
than  22  pages  are  needed  will  the  search  be  performed.  Since  this  rarely 
happens,  as  mentioned  earlier,  the  processing  time  is  barely  affected. 

The  program  model  of  the  PMMU  consists  of  six  registers: 

CPU  (or  User)  Root  pointer  (CRP) 
Supervisor  Root  pointer  (SRP) 
Translation  Control  Register  (TC) 
Transparent  Translation  Register  1  (TTO) 
Transparent  Translation  Register  2  (TT1) 
MMU  Status  Register  (MMUSR) 

The  root  pointer  registers  hold  translation  tree  starting  addresses.  You 
can  choose  between  separate  trees  for  user  and  supervisor  programs  or  a 
single  common  tree.  If  only  one  tree  is  used,  its  address  must  be  in  the 
CPU  root  pointer. 

The  transparent  translation  registers  make  it  possible  to  reference  any 
two  address  regions  without  address  translation.  Their  logical  addresses 
then  are  the  same  as  the  physical,  as  though  the  MMU  were  disabled. 
This  function  is  useful  for  larger  areas  which  require  quick  access,  for 
example  screen  memory.  Since  such  an  area  consists  of  many  pages  that 
are  accessed  in  no  particular  sequence,  the  22  ATC  entries  are  not 
sufficient  to  avoid  frequent  searching  of  the  translation  tree  tables.  It  is 
more  efficient  to  reference  these  areas  without  the  MMU. 
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MMU  Transparent  Translation  Registers  TTO  and  TT1: 


BitNr.: 

Function: 

31-24 

Address  bits  31  through  24  of  the  transparent  region 

23-16 

Mask  for  above  address  bits 

15 

E  -  Enable  bit  for  transparent  region 

14-11 

Unused 

10 

CI  -  Cache  inhibit 

9 

R/W  -  Read/write 

8 

RWM  -  Read/write  mask 

7 

Unused 

6-4 

Function  code  base  of  region 

3 

Unused 

2-0 

Function  code  mask 

Address  bits  and  mask 

The  transparent  window  has  a  minimum  size  of  16  Meg.  The  eight 
address  bits  in  the  TTx  register  specify  its  address.  The  masking  bits  can 
be  used  to  define  larger  windows.  When  one  of  these  is  set,  its 
corresponding  address  bit  is  ignored. 

Enable  bit  (E) 

Setting  the  E  bit  to  1  enables  the  transparent  region  defined  by  the  TTx 
register. 

Cache  inhibit  (CI) 

The  CI  bit  allows  you  to  choose  whether  or  not  values  from  the 
transparent  region  should  be  placed  in  the  data  and  instruction  caches 
(1  =  no  caching). 

R/W  and  RWM 

The  R/W  bit  specifies  the  type  of  access  that  should  be  transparent: 


R/W  =  0      Write  access 
R/W  =  1      Read  access 


To  grant  both  types,  the  RWM  bit  must  be  set: 


RWM  =  0      Access  according  to  R/W  bit 
RWM  =  1      Ignore  R/W  bit 


672 


11.2  The  68030 


Function  code  base  and  function  code  mask 

The  base  field  determines  the  region's  function  code.  If  you  want  it  to  be 
transparent  for  more  than  one  specific  function  code,  you  can  use  the 
mask  to  choose  which  bits  of  the  base  field  should  be  ignored  (mask  =  1). 

Translation  Control  Register  (TC) 

The  TC  register  controls  the  construction  of  the  translation  tree.  The  root 
of  this  tree  is  found  in  the  CPU  root  pointer  register.  That  address  points 
to  the  first  table,  or  level,  of  the  tree.  Each  entry  in  this  highest  table 
(level  A)  points  to  a  table  at  the  next  level  (level  B).  The  tree  continues  to 
branch  until  the  lowest  level,  which  contains  the  actual  page  addresses,  is 
reached. 


Page  Pointer  Tables 

The  logical  address  consists  of  up  to  six  fields,  which  are  used  to  move 
through  the  various  levels  of  tables.  The  fields  (with  the  exception  of  the 
first  one)  represent  indexes  for  successive  branches  of  the  translation 
tree. 

Here  is  how  the  individual  fields  look  in  relation  to  the  logical  address: 
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Bits  31 

Bits  31 -IS 

Bits  31-IS-TIA 

Bits  31-IS-TIA-TIB 

Bits  31-IS-TIA-TIB-TIC 

Bits  31-IS-TIA-TIB-TIC-TID 

Shown  another  way: 
Logical  address: 


to  31 -IS 
to  31-IS-TIA 
to  31-IS-TIA-TIB 
to  31-IS-TIA-TIB-TIC 
to  31-IS-TIA-TIB-TIC-TID 
to  bit  0 


Ignored 
Table  A  index 
Table  B  index 
Table  C  index 
Table  D  index 
Page  offset 


31 BitNr 0 

IS|TIA|TIB|TIC|TID|Pageoffset 


The  IS  (initial  shift)  field  is  a  series  of  up  to  15  bits,  starting  with  bit  31, 
which  are  to  be  ignored  by  the  MMU.  Because  the  IS  bits  are  not 
considered,  the  same  physical  address  is  allocated  by  the  MMU 
regardless  of  their  value,  so  the  effect  of  the  shift  is  to  reduce  the  logical 
address  space  accordingly.  Where  IS  =  the  number  of  bits  in  the  initial 
shift  field,  the  shift  reflects  a  reduction  of  address  space  by  a  factor  of 
2IS. 

TIA  through  TID  are  table  indexes  A  through  B.  Each  index  can  be  from 
0  to  15  bits  long,  except  for  TIA,  which  must  be  at  least  1  bit.  With  a  TIA 
length  of  five  bits,  for  example,  the  five  most  significant  bits  of  the  logical 
address  (after  the  IS)  are  used  as  an  index  to  the  highest  level  of  the 
translation  tree.  This  table  must  then  have  25,  or  32  entries.  Each  entry 
points  to  a  table  at  level  B.  The  size  of  the  TIB  field  (again  as  a  power  of 
2)  indicates  the  number  of  entries  in  the  level  B  tables.  This  pattern 
continues  down  to  level  D.  The  remaining  bits  of  the  logical  address  form 
the  page  offset,  the  relative  position  of  the  desired  memory  location 
within  the  page. 

It  is  not  necessary  to  use  all  four  levels  of  tables.  The  translation  tree 
terminates  when  a  null  TIx  field  is  reached.  If  TIC  =  0,  the  tree  is  limited 
to  levels  A  andB. 

Even  a  fifth  level  can  be  used  by  setting  the  FCL  (function  code  lookup) 
enable  bit  in  the  TC  register.  As  the  name  suggests,  the  function  code  bits 
then  become  part  of  the  table  lookup  algorithm.  This  is  implemented  with 
another  table,  consisting  of  eight  entries,  preceding  the  A  level.  The  root 
pointer  points  to  this  table.  The  function  code  bits  are  used  to  select  from 
the  eight  entries,  which  in  turn  point  to  tables  of  level  A. 
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Translation  Control  Register  Layout 


BitNr. 

Name 

Function 

31          | 

E 

Enables  the  MMU 

30-26 

. 

Unused 

25 

SRE 

Enables  supervisor  root  pointer  (separate  translation 
trees  for  user  and  supervisor  mode) 

24 

FCL 

Function  code  lookup  enable 

23-20 

PS 

Pagesize: 
1000 -256  Bytes 
1001  -512  Bytes 
1010-1  KByte 
1011  -2  KByte 
1100 -4  KByte 
1101  -8  KByte 
1110 -16  KByte 
1 1 1 1  -  32  KByte 

19-16 

IS 

Initial  Shift  (0  to  15) 

15-12 

TIA 

Table  Index  A  (1  to  15) 

11-8 

TIB 

Table  Index  B  (0  to  15) 

7-4 

TIC 

Table  Index  C  (0  to  15) 

3-0 

TID 

Table  Index  D  (0  to  15) 

PS,  IS,  TIA  -  TID  must  clearly  establish  the  use  of  the  individual  bits  of  the 
logical  address.  Their  sum  must  always  be  32.  Otherwise  the  MMU 
generates  an  MMU  configuration  exception. 

Elements  of  the  Translation  Tree 

The  various  tables  of  the  translation  tree  can  contain  different  types  of 
entries  called  descriptors.  A  descriptor  consists  of  a  pointer  to  a  memory 
page  or  to  the  next  level  of  tables,  as  well  as  control  information  about 
the  subsequent  structure  of  the  tables  or  about  the  memory  that  the 
descriptor  addresses.  Not  every  descriptor  type  contains  all  the  following 
fields: 

DT   Descriptor  type 

This  2-bit  field  can  contain  the  following: 

Invalid,  DT=0 

If  the  MMU  encounters  an  invalid  descriptor,  it  terminates  its  search 
and  reports  a  bus  error  to  the  CPU.  Invalid  descriptors  allow  the 
translation  tree  to  start  out  in  skeleton  form  (in  which  these 
descriptors  point  to  as  yet  undefined  locations),  and  to  be 
completed  only  as  needed  (when  bus  errors  occur). 
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Page  descriptor,  DT=1 

A  page  descriptor  also  terminates  the  MMU's  search,  but  signals  a 
successful  completion  because  it  contains  the  address  of  the  desired 
memory  page. 

Valid  4  bytes,  DT=2 

This  designates  a  valid  pointer  to  a  table  of  the  next  lower  level.  All 
entries  in  this  table  must  be  4  bytes  long. 

Valid  8  bytes,  DT=3 

Same  as  above,  but  the  table  being  addressed  must  contain  8  byte 
entries. 

U     Used 

This  bit  is  automatically  set  when  the  MMU  reads  the  descriptor.  It 
can  be  used,  for  example,  to  determine  whether  a  certain  memory 
page  has  been  accessed. 

M     Modified 

This  bit  indicates  a  write  access  to  the  allocated  memory  page. 

WP  Write  protect 

If  this  bit  is  set  in  one  of  the  descriptors  read  during  a  table  search,  a 
corresponding  page  may  not  be  written.  This  is  useful,  for  example, 
to  prohibit  subsequent  changes  after  modifying  Kickstart  in  RAM. 

S      Supervisor  only 

This  bit  designates  a  table  or  memory  page  that  may  be  referenced 
by  supervisor  programs  only.  Reference  by  user  programs  results  in 
a  bus  error. 

Q    Cache  inhibit 

Many  addresses  may  not  be  cached.  This  is  true  primarily  for  the 
various  peripheral  chip  registers  or  for  areas  of  memory  that  can  be 
changed  independently  of  the  CPU  (the  dual-ported  RAM  on  the 
PC/AT  plug-in  board  and  chip  memory). 
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Caching  can  be  turned  off  for  the  corresponding  memory  pages 
using  the  CI  bit.  When  the  CI  bit  is  set,  the  CPU  does  not  transfer 
these  pages  to  the  cache  as  they  are  read. 

LIMIT  and  L/U  bit 

The  15-bit  limit  field  can  be  used  to  limit  the  index  to  the  next  table. 
The  MMU  checks  to  see  if  the  index  value  contained  in  the  logical 
address  is  higher  than  the  limit  when  the  L/U  bit  =  0,  or  lower  than 
the  limit  when  L/U  =  1.  The  L/U  (lower/upper)  bit  determines 
whether  the  index  has  a  lower  or  an  upper  limit. 

Page  address 

This  24-bit  field  contains  the  physical  page  address  that 
corresponds  to  the  requested  logical  address.  Depending  on  the 
page  size  (see  Translation  Control  Register),  some  of  the  bits  are 
unused.  With  4K  pages,  12  bits  are  needed  to  address  a  location 
within  the  page.  These  are  taken  directly  from  the  logical  address 
(the  page  offset).  Then  only  the  upper  20  bits  of  the  page  address 
field  are  used  to  establish  the  address  of  the  page. 

Table  address 

This  28-bit  field  contains  the  base  address  of  the  descriptor  table  of 
the  next  lower  level. 

Descriptor  address 

This  is  a  30-bit  pointer  to  another  descriptor.  It  is  used  only  by 
indirect  descriptors  (see  the  following). 

The  Various  Descriptor  Types 

Bits  labeled  "unused"  can  be  used  to  store  values  as  needed  (e.g., 
additional  status  information  for  memory  management). 
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Root  pointer  (either  CPU  or  Supervisor  Root  Pointer  Register) 


LW       BitNr.        Function 


31 

30-16 

15-2 

1-0 

31-4 

3-0 


LAI  bit  for  limit 

Limit  value 

Must  be  zero 

DT  (descriptor  type)  of  root  pointer 

Table  address 

Unused 


Short  Format  Table  Descriptor  (4  bytes) 


BitNr.       Function 


31-4 
3 

2 
1-0 


Table  address 

U  (Used) 

WP  (Write  protect) 

DT  (Descriptor  type)  =  2 


Long  Format  Table  Descriptor  (8  bytes) 


LW 

BitNr. 

Function 

0 

31 

LAI  bit  for  limit 

0 

30-16 

Limit  value 

0 

15-10 

Must  be  1  's 

0 

9 

Must  be  zero 

0 
0 

8 
7-4 

S  (Supervisor  only) 
Must  be  zero 

0 
0 
0 

1 

3 
2 

1-0 
31-4 

U  (Used) 

WP  (Write  protect) 

DT  (Descriptor  type)  =  3 

Table  address 

1 

3-0 

Unused 

Short  Format  Page  Descriptor  (4  bytes) 


BitNr. 

Function 

31-8 

Page  address 

7 

Must  be  zero 

6 

CI  (Cache  inhibit) 

5 

Must  be  zero 

4 

M  (Modified) 

3 

U  (Used) 

2 

WP  (Write  protect) 

1-0 

DT  (Descriptor  type)  =  1 
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Long  Format  Page  Descriptor  (8  bytes) 


LW       BitNr. 


Function 


31 

30-16 

15-10 

9 

8 

7 

6 

5 

4 

3 

2 

1-0 

31-8 

7-0 


L/U  bit  for  limit 

Limit  value 

Must  be  1's 

Must  be  zero 

S  (Supervisor  only) 

Must  be  zero 

CI  (Cache  inhibit) 

Must  be  zero 

M  (Modified) 

U  (Used) 

WP  (Write  protect) 

DT  (Descriptor  type)  =  1 

Page  address 

Unused 


Short  Invalid  Descriptor  (4  bytes) 


BitNr.       Function 


31-2 
1-0 


Unused 

DT  (Descriptor  type)  =  0 


Long  Invalid  Descriptor  (8  bytes) 


LW       BitNr. 


Function 


31-2 

1-0 

31-0 


Unused 

DT  (Descriptor  type)  =  0 

Unused 


Short  Format  Indirect  Descriptor  (4  bytes) 


BitNr.       Function 


31-2 
1-0 


Descriptor  address 

DT  (Descriptor  type)  =  2  or  3 


Long  Format  Indirect  Descriptor  (8  bytes) 


LW       BitNr. 


Function 


31-2 
1-0 
31-2 
1-0 


Unused 

DT  (Descriptor  type)  =  2  or  3 

Descriptor  address 

Unused 
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Early  Termination  and  Memory  Blocks 

Normally  page  descriptors  are  in  the  lowest  level  of  the  tree  and  table 
descriptors  in  the  upper  level.  A  page  descriptor  that  occurs  at  a  higher 
level  is  called  an  "Early  Termination  (ET)"  page  descriptor.  It  can  be 
used  to  allocate  a  consecutive  area  of  physical  addresses  to  all  logical 
addresses  belonging  to  a  table  entry. 

Assume  that  an  ET  page  descriptor  exists  at  the  next-to-last  table  level, 
the  last  level  contains  4096  entries,  and  the  page  size  is  8K.  A  32  Meg 
block  (4096  x  8K)  is  then  referenced  by  this  ET  descriptor.  The 
descriptor's  page  address  field  contains  the  physical  base  address  of  the 
block.  The  logical  base  address  is  any  bit  combination  that  references  the 
ET  descriptor  in  the  translation  tree.  The  bits  of  the  logical  address  that 
normally  would  select  one  of  the  4096  entries  of  the  lowest  level  table 
now  select  the  referenced  page  directly  within  the  32  Meg  block.  The 
lowest  level  table  can  be  eliminated. 

Here  is  how  the  various  bits  in  the  logical  address  are  used  relative  to  the 
previous  example: 


Values  in  the  Translation  Control  Register: 

IS  =  0,  TIA  =  7,  TIB  =  12,  TIC  &  TID  =  0,  PS  =  8  KByte 


Logical  address  without  ET  descriptor: 

BitNr.  31  ...  24  ... 

Pointer  to  Table  A  Pointer  to  Table  B 


12...  o 

Address  within  the 
memory  page 


Logical  address  with  ET  descriptor  in  Table  A: 

BitNr.  31...                    24...  12...  o 
Pointer  to  Table  A          Page  number  in  32  Meg  Address  within  the 
memory  page  block 


An  ET  descriptor  can  also  replace  more  than  one  level  of  tables  if  it 
occurs  at  a  higher  (previous)  level  of  the  translation  tree.  You  can 
imagine  this  as  a  tree,  where  the  root  pointer  is  the  trunk,  the  tables  of  the 
intermediate  levels  are  the  limbs  and  branches,  and  the  page  descriptors 
at  the  lowest  (last)  level  are  the  leaves.  An  ET  descriptor  replaces,  a 
branch  or  limb  with  a  single  "hyper-dimensional"  leaf,  which  represents 
all  the  leaves  this  branch  or  limb  carries. 
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Indirect  Descriptors 

Another  special  feature  of  the  translation  tree,  whose  structure  has 
already  been  described,  is  the  indirect  descriptor.  This  descriptor  occurs 
in  place  of  a  page  descriptor  at  the  lowest  level  of  the  translation  tree  and 
must  point  to  a  page  descriptor  in  some  other  branch  of  the  tree.  It  allows 
two  different  logical  addresses  to  be  assigned  to  the  same  physical  page. 
This  would  apply  to  global  data  structures  or  when  the  tree  is  divided 
into  supervisor  and  user  sections. 

The  same  effect  is  achieved  simply  by  placing  the  same  page  address  into 
two  page  descriptors  at  different  parts  of  the  tree.  But  in  this  case,  the 
Used  and  Modified  bits  of  both  descriptors  must  always  be  checked  to 
determine  whether  the  page  has  been  accessed.  Indirect  descriptors  can 
provide  significant  time  savings  in  the  case  of  global  data  structures, 
where  not  just  two,  but  a  multiplicity  of  descriptors  may  point  to  the 
same  physical  address,  since  these  structures  can  be  accessed  by  every 
task. 

The  MMU  Instructions 

The  MMU,  like  every  coprocessor  in  a  68030  system,  adds  its  own 
commands  to  the  instruction  set  of  the  CPU. 

The  MMU  recognizes  the  following  instructions: 


IPMQVE 


The  PMOVE  instruction  accesses  the  registers  of  the  MMU:  TC,  SRP, 
CRP.TTOorTTl. 

Syntax:  PMOVE  <effective  address  (ea)>,  MMU-register 

PMOVE  MMU-register,<ea> 

PMOVEFD  Since  changing  the  contents  of  an  MMU- 
register  usually  invalidates  the  current  values  in  the 
ATC  (Address  Translation  Cache),  the  ATC  is  cleared 
with  every  PMOVE  instruction  that  writes  to  one  of 
these  registers.  This  can  be  prevented  with  PMOVEFD 
(Flush  Disable). 

Syntax:  PMOVEFD  <ea>,  MMU-register 
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IPFLUSH 


Clears  an  entry  in  the  ATC. 
Syntax:  PFLUSH(An) 

IPFLUSHA  | 

Clears  all  entries  in  the  ATC. 
Syntax:  PFLUSHA 


PLOAD 


Performs  a  table  search  for  the  given  logical  address  and  function  code 
and  writes  the  physical  address  to  the  ATC.  The  search  can  be  performed 
in  advance  for  routines  where  time  is  critical. 

The  PLOAD  instruction  has  two  variants:  PLOADR  (read)  and  PLOADW 
(write).  In  PLOADW,  the  MMU  sets  the  Modified  bit  in  the  page 
desciptor,  as  though  a  write  access  to  this  logical  address  had  occurred. 

The  Used  bit  is  always  set  in  PLOAD  instructions. 

Syntax:  PLOADR         <function  code>,<ea> 

PLOADW        <function  code>,<ea> 


PTEST 


The  PTEST  instruction  can  be  used  to  find  the  cause  of  a  bus  error  in  the 
exception  handler.  The  MMU  performs  a  table  search  for  the  logical 
address  (this  can  be  fetched  from  the  stack  after  a  bus  error),  and  sets  the 
bits  in  the  Status  Register  (see  the  following)  to  indicate  whether  an 
invalid  descriptor  was  found,  a  LIMIT  exceeded,  etc. 

Syntax:  PTEST  <function  code>,<ea>,level,An 

"level"  is  the  maximum  number  of  table  levels  which 
are  to  be  searched. 

level=0  -  look  only  in  ATC 
level=7  -  search  all  table  levels 
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PTEST  also  has  two  variants,  PTESTR  and  PTESTW. 
The  distinction  is  pertinent  only  when  PTEST  level  =  0, 
and  one  of  the  two  transparent  addresses  (TTx  registers) 
is  referenced. 


The  MMU  Status  Register  (MMUSR) 


BitNr. 

Name 

15 

B  -  Hardware  bus  error  in  table  search 

14 

L  -  LIMIT  error  (invalid  for  PTEST  level  0) 

13 

S  -  Supervisor  only  (invalid  for  PTEST  level  0) 

12 

Must  be  zero 

11 

W  -  Write  protected 

10 

I  -  Invalid 

9 

M  -  Modified 

8&7 

Must  be  zero 

6 

T  -  Transparent  region  (only  for  PTEST  level  0) 

5-3 

Must  be  zero 

2-0 

Number  of  table  levels  searched  (0  with  PTEST  level  0) 

For  PTEST  with  level  =  0,  the  I  bit  signals  that  the  desired  logical  address 
has  no  ATC  entry  (in  which  case,  a  level  7  PTEST  will  return  additional 
information),  or  that  a  hardware  bus  error  has  occurred  in  searching  the 
table  (in  which  case  the  B  bit  also  is  set). 

For  PTEST  with  level  >  0,  the  I  bit  indicates  that  an  invalid  descriptor  was 
found,  a  LIMIT  was  exceeded  (L  bit  =  1),  or  a  bus  error  occurred  (B  bit  = 
1). 

11.2.2        The  Floating  Point  Coprocessor 

The  microprocessor  in  a  desktop  computer  like  the  A3000  is  normally 
responsible  for  the  execution  of  all  program  instructions.  But  even  the 
68030,  one  of  the  most  powerful  processors,  has  its  limits,  namely  in  the 
processing  of  data  types  that  are  not  directly  supported  in  its  hardware 
design. 

Attempts  must  be  made,  then,  to  construct  these  from  other  available  data 
types  and  handle  their  processing  by  using  software.  The  data  types  that 
the  68030  supports  directly  were  listed  in  the  previous  chapter.  An 
example  of  one  that  is  not  directly  supported,  but  which  nevertheless  can 
be  effectively  handled  with  the  existing  types,  is.  the  character  string. 
This  usually  consists  of  a  variable-length  sequence  of  bytes  terminated 
by  a  zero.  Using  a  small  loop  and  the  "byte"  data  type,  it  is  possible  to 
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perform  all  the  elementary  character  string  operations,  such  as  copying, 
comparing  and  clearing. 

Another  data  type  not  directly  supported,  and  even  more  essential  in  the 
Amiga  than  the  character  string,  is  the  bit-map  graphic.  Bit-map  graphics 
are  used  to  build  a  representation  in  memory  of  the  visible  contents  of  a 
screen.  Elementary  bit-map  operations,  such  as  drawing  lines  or  filling 
surfaces,  require  multiple  operations  with  individual  memory  bits. 
Unfortunately,  the  bit-by-bit  manipulation  of  data  is  not  very  effective  in 
a  processor  optimized  for  32  bit  integers. 

For  this  reason,  Commodore  has  equipped  the  Amiga  with  an  integrated 
circuit  called  the  Blitter.  While  not  an  actual  coprocessor  in  Motorola's 
sense  of  the  word,  it  can  perform  independent  bit-map  operations  much 
faster  than  the  68000. 

Functions 

The  FPU  now  places  data  types  unknown  to  the  68030  but 
indispensable  for  a  variety  of  computer  applications.  These  are  the 
floating-point  numbers. 

The  68030  recognizes  only  a  limited  range  of  integer  numbers,  which  can 
be  expressed  in  mathematical  set  notation  as  follows:  Z  =  {X  I  -231  <=  X 
<  231  }  xnis  set  0f  numbers  may  suffice  for  the  normal  tasks  of  an 
operating  system  and  many  application  programs,  but  for  the  solution  of 
mathematical  problems  it  must  be  expanded. 

The  drawing  of  a  circle  presents  a  simple  example.  The  formula  for  a  point 
on  the  circumference  is: 


< 


X-coordinate  =  sin  angle  *  radius 
Y-coordinate  =  cos  angle  *  radius 


The  final  result,  the  point's  "x:"  and  "y"  coordinates,  must  be  whole 
numbers,  since  there  is  no  such  thing  as  half  a  pixel  position  in  graphic 
memory.  But  computations  with  the  trigonometric  sine  and  cosine 
functions  require  a  greater  universe  than  whole  numbers,  since  these 
functions  return  values  from  the  set  of  real  numbers.  The  real  numbers, 
when  expressed  in  decimal  form,  have  a  fractional  component  that  either 
terminates,  repeats  periodically  or  repeats  at  random. 


684 


11.2  The  68030 


A  binary  format,  that  can  represent  the  greatest  possible  subset  of  these 
numbers,  must  be  found.  We  are  at  best  limited  to  a  subset,  because  any 
machine  format  is  finite  (i.e.,  limited  to  a  certain  number  of  places).  The 
limitations  imposed  on  our  available  universe  are  twofold,  affecting  both 
range  and  precision.  First,  there  is  a  minimum  and  a  maximum  number  that 
the  format  can  represent.  Secondly,  the  fractional  digits  of  repeating 
decimal  numbers  (e.g.,  pi)  must  eventually  (as  justified  by  considerations 
of  memory  and  computing  time)  be  truncated. 

Over  time,  the  floating-point  representation  has  gained  general 
acceptance,  since  it  is  applied  relatively  simply  to  computers  and  it  is 
adequate  for  almost  all  mathematical  computations. 

Floating-point  format  corresponds  to  exponential  notation  in 
mathematics,  where  a  number  greater  than  or  equal  to  1  and  less  than  10, 
called  the  mantissa  (the  decimal  part  of  a  logarithm),  is  multiplied  by  a 
power  of  10,  the  exponent.  Some  examples  are: 


Normal  notation 

Exponential  notation 

27 

1,500,000 
0.5 
0.0000042 

->2.7 
->1.5 
->5 
->4.2 

A 

Mantissa 

X 
X 
X 
X 

101 
106 

10-1 

10-6 

A 

Exponent 

The  exponent  in  floating-point  machine  format  always  refers  to  base  2. 

This  notation  permits  the  representation  of  both  very  large  and  very  small 
numbers  without  long  strings  of  zeros.  The  FPU  68881/68882  can 
perform  computations  on  these  numbers  directly,  just  as  the  68030  does 
with  integers. 

Internal  Design  -  The  Program  Model 

From  the  programmer's  point  of  view,  the  FPU  has  11  registers  (see  the 
following  illustration).  Eight  of  them  are  universal  floating-point  data 
registers,  designated  FP0  -  FP7.  Each  is  80  bits  wide  and  can  accept  one 
number.  In  addition  to  these  are  the  Control  Register  (FPCR),  which 
controls  the  FPU's  mode  of  operation,  the  Status  Register  (FPSR),  which 
holds  flag  bits  like  its  counterpart  in  the  68030,  and  the  Instruction 
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Address  Register  (FPIAR).  This  last  register  stores  the  address  of  the 
current  FPU  instruction,  for  reasons  that  will  be  seen  later. 


79 

63 

0 

31 


23 


15 


Ifcxceplion  I      Mode      I 
Enable   |     Control     I 


I  Condnion  |  Qlloti.rt    I  Exceplion  I    Accrued    I 
|     Code     |  wmm    |     Status    |  Exception  I 


J 


FPO 
FP1 
FP2 
FP3 
FP4 
FPS 
FP6 
FP7 

FPCR 

FPSR 

FPIAR 


Floating  Point 
Data  Registers 


Status 
Register 

Instruction  Address 
Register 


Floating-point  Data  Format 

Floating-point  Data  Formats 

Internally  the  FPU  operates  exclusively  on  a  single  data  type  called 
extended  real.  This  is  the  only  data  type  that  can  be  placed  in  one  of  the 
FPU  data  registers.  It  is,  however,  only  one  of  seven  types  with  which  we 
may  actually  work.  All  others  are  automatically  converted  by  the  FPU  to 
extended  real  format  before  being  used.  When  a  value  is  transferred  from 
one  of  the  eight  FPU  data  registers  to  main  memory,  the  corresponding 
conversion  again  takes  place. 

The  byte,  word,  and  longword  integer  formats  are  identical  to  those  of 
the  68030,  but  are  also  handled  internally  as  extended. 

Single  real  and  double  real  formats  differ  only  in  size,  with  one  long  word 
for  single  and  two  for  double.  Extended  real  format  consists  of  three  long 
words,  but  16  bits  are  not  used,  since  the  FPU  data  registers  are  only  80 
bits  wide. 

Packed  decimal  real  format  differs  from  the  other  six  formats  in  that  it 
represents  numbers  by  the  base-ten  (decimal)  rather  than  base-two 
(binary)  system. 
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The  mantissa  undergoes  special  handling  in  single  and  double  real 
formats.  Basically  all  floating-point  numbers  are  stored  in  normalized 
form.  This  means  that  the  exponent  is  chose  to  produce  a  mantissa  in  the 
range  10°  <=  mantissa  <  10*  (1  <=  mantissa  <  10).  One  writes  not  35  * 
103  but  3.5  *  10*,  and  5  *  10'4  instead  of  0.5  *  10"3.  There  is  exactly 
one  place  before  the  decimal  point,  whose  position  is  established  in  all 
formats. 


m 
I 


8-BIT 
EXP. 


23-BIT 
FRACTION 


SIGN  OF  FRACTION 


11-BIT 

EXP. 


L 


52-BIT 
FRACTION 


SIGN  OF  FRACTION 


14-BIT 
EXPONENT 


ZERO 


64-BIT 
MANTISSA 


SIGN  OF  MANTISSA 
80 67 


IT 


IMPLICIT  BINARY  POINT 


91 


I  3-DK3IT 
'     EXP. 


17-DIGIT   : 
MANTISSA  : 


DOUBLE  REAL 


EXTENDED  REAL 


PACKED  DECIMAL  REAL 


I —  IMPLICIT  DECIMAL  POINT 
■2  BITS.  USED  ONLY  FOR  t  INFINITY  OR  NANS,  ZERO  OTHERWISE 
.SIGN  OF  EXPONENT 
■—SIGN  OF  MANTISSA 

UNLESS  A  BINARY-TO-DECIMAL  CONVERSION  OVERFLOW  OCCURS 


Real  Formats 

Similarly,  a  mantissa  in  the  binary  system  would  be  governed  as  follows: 
2°  <=  mantissa  <  21  (1  <=  mantissa  <  2).  The  bit  before  the  "decimal" 
point  must  always  be  1.  To  save  space,  it  is  simply  dropped  in  single  and 
double  format.  The  first  bit  of  the  mantissa  represents  the  first  place  after 
the  "decimal"  point,  with  a  leading  1  always  implied. 

In  extended  format  this  bit  still  exists  and  can  be  set  to  zero.  The  same  is 
true  of  packed  decimal  format.  Such  a  number  is  said  to  be  unnormalized. 
It  is  normalized  by  the  FPU  before  any  operation  on  it  is  begun.  The 
result  of  an  FPU  instruction  is  never  an  unnormalized  number. 

The  exponent  (except  in  packed  decimal  format)  is  constructed  as  an 
unsigned  binary  number,  from  which  the  sign  is  then  reclaimed  by 
subtracting  an  offset.  Depending  on  the  format,  the  offset  is  127, 1023  or 
16383.  For  a  number  in  double  real  format,  for  example,  the  value  1023  in 
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the  exponent  field  signifies  an  actual  exponent  value  of  0,  1022  is  -1,  and 
so  on. 

The  reason  for  this  lies  in  the  68030.  By  virtue  of  this  special 
representation  of  the  exponent  and  the  fact  that  the  mantissa  sign 
appears  in  the  MSB  of  the  long  word,  two  floating-point  numbers  can  be 
compared  by  the  CMP  instruction,  without  having  to  call  upon  the  FPU. 

For  this  purpose  they  behave  just  like  normal  integers. 

Status  and  Control  Registers 

The  Status  Register  is  subdivided  into  four  function  groups  of  one  byte 
each: 

•  Condition  Code  Byte 

•  Quotient  Byte 

•  Exception  Byte 

•  Accrued  Exception  Byte 

Condition  Code  Byte  (FPCC  -  Floating  Point  Condition  Code) 


BitNr.: 
Function: 

N 
Z 
I 
NAN 


31 
0 


30 
0 


29 
0 


28 
0 


27 
N 


26 

Z 


25 

I 


24 
NAN 


Negative  result 
Result  is  0 

Result  is  +  or  -  infinity 
Result  is  not  a  number 


These  four  bits  fulfill  the  same  purposes  as  the  N,  C,  Z  and  X  bits  in  the 
Status  Register  of  the  68030.  They  are  set  according  to  the  data  type  of 
the  result  following  every  computation  operation.  With  the  aid  of  these 
bits,  you  can  use  the  FBcc  instruction  to  build  conditional  jumps  into  a 
program,  making  program  flow  dependent  upon  FPU  computation 
results. 

Quotient  Byte 


BitNr.:        23     22     21     20     19     18     17     16 
Function:    S      MSB Quotient LSB 
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This  byte  is  set  after  only  two  instructions:  modulo  and  IEEE-REST. 
Both  compute  the  remainder  of  a  division.  Instead  of  throwing  away  the 
inner  of  a  computed  quotient,  it  is  placed  in  this  byte.  If  it  is  greater  than 
seven  bits,  the  higher  order  ones  are  dropped.  The  sign  of  the  quotient 
appears  in  the  S  bit. 


Exception  Byte 

BitNr.: 

15            14          13             12          11           10 

9           8 

Func: 

BSUN     SNAN    OPERR    OVFL    UNFL     DZ 

INEX1    INEX2 

BSUN 

Branch  /  Set  On  Unordered 

SNAN 

Signaling  Not  A  Number 

OPERR 

OPerand  ERRor 

OVFL 

OVerFLow 

UNFL 

UNderFLow 

DZ 

Divide  by  Zero 

INEX2 

INEXact  Operation 

INEX1 

INEXact  decimal  input 

Just  as  the  68030  calls  an  exception  routine  in  case  of  error,  for  example, 
a  supervisor  instruction  executed  in  user  mode,  the  same  can  be  done  by 
the  coprocessor.  In  fact,  computations  with  floating-point  numbers  can 
cause  several  types  of  errors. 

These  errors  are  reflected  in  the  Exception  byte. 

Whether  an  exception  routine  will  actually  be  called  depends  on  the 
upper  byte  of  the  Control  Register,  the  Exception  Enable  byte.  It  has 
exactly  the  same  layout  as  the  Exception  byte  in  the  Status  Register.  If  a 
bit  in  the  Enable  byte  is  set  and  the  corresponding  exception  occurs,  the 
68030  calls  the  assigned  exception  routine.  If  an  exception  is  disabled 
by  clearing  the  corresponding  bit,  checking  the  Exception  byte  will 
reveal  whether  an  error  has  occurred,  but  the  exception  procedure  will 
not  be  called. 
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Accrued  Exception  Byte 


BitNr.:  7  6  5  4  3 

Function:       IOP      OVFL       UVFL        DZ        INEX 


IOP 

OVFL 

UNFL 

DZ 

INEX 


Invalid  OPeration  (BSUN  or  SNAN  or  OPERR) 

OVerFLow  (OVFL) 

UNderFLow  (UNFL  and  INEX2) 

Divide  by  Zero  (DZ) 

INEXact  Operation  (INEX1  or  INEX2  or  OVFL) 


Sometimes  you  may  prefer  simply  not  to  permit  any  exceptions,  if  for  no 
other  reason  than  to  avoid  having  to  program  the  exception  handlers.  In 
this  case  the  Exception  byte  would  have  to  be  checked  after  every 
floating-point  computation,  since  any  bits  set  are  cleared  for  each  new 
operation. 

Here  the  Accrued  Exception  byte  is  useful.  If  the  FPU  changes  a  bit  in 
the  Exception  byte,  the  bits  in  the  Accrued  byte  are  set  as  previously 
shown.  Thus  IOP  is  activated  when  BSUN,  SNAN  or  OPERR  =  1 . 

Unlike  in  the  Exception  byte,  the  bits  in  the  Accrued  byte  retain  then- 
status.  Once  set,  they  are  cleared  only  by  the  explicit  writing  of  a  0  in  the 
Status  Register. 

This  allows  you  to  perform  a  series  of  computations  and  wait  until  their 
completion  to  determine  whether  any  errors  occurred. 

Control  Register  -  Mode  Control  Byte 


BitNr.: 

7 

6       5            4         3           2 

1 

0 

Function: 

PREC 

RND                0           0 

0 

0 

PREC 

Rounding  Precision 

00 

Extended 

01 

Single 

10 

Double 

RND  -  Rounding  Mode 

00 

round  to  nearest  -  RN 

01 

round  toward  zero  -  RZ 

10 

round  toward  minus  infinity  -  RM 

1 1 

round  toward  plus  infinity  -  RP 
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Precision  bits  are  used  to  adjust  the  precision  to  which  a  result  should  be 
rounded.  Normally  these  bits  are  set  to  Extended  (both  0),  since  internal 
processing  takes  place  on  extended  numbers.  A  result  stored  in  single  or 
double  precision  is  rounded  automatically,  regardless  of  the  PREC  bits. 

The  rounding  mode  determines  what  the  coprocessor  will  do  when  a 
number  cannot  be  represented  exactly  with  the  available  precision. 
Internally  it  computes  with  three  additional  bits  for  the  mantissa.  If  these 
are  not  all  zero  as  the  result  of  a  computation,  rounding  is  required.  The 
actual  value  lies  between  two  choices,  which  are  numbers  that  can  be 
represented  with  the  available  number  of  bits  in  the  mantissa.  One  of 
these  must  be  chosen  as  the  result.  How  the  FPU  proceeds  in  this  choice 
is  determined  by  the  two  RND  bits: 

Mode  RN  always  rounds  to  the  nearer  of  the  two  possibilities  previously 
described.  If  they  are  equidistant,  the  FPU  chooses  the  even  one  (LSB  = 
0). 

Mode  RZ  rounds  to  the  one  with  the  smaller  absolute  value  (i.e.,  the  one 
closer  to  zero). 

Mode  RM  always  chooses  the  smaller  number,  RP  chooses  the  larger. 

The  FPU  Instruction  Set 

As  we  mentioned  earlier,  all  FPU  assembler  instructions  are  simply 
considered  extensions  of  the  68030  instruction  set  and  can  be  mixed 
with  68030  instructions  as  desired.  Processing  occurs  in  parallel.  A  main 
processor  instruction  that  follows  an  FPU  instruction  can  begin 
executing  as  soon  as  the  68030  has  given  the  FPU  the  data  it  needs. 
Only  upon  encountering  another  FPU  instruction  must  the  CPU  wait  for 
the  first  one  to  be  completed. 

The  only  exceptions  are  those  FPU  instructions  that  transfer  data  from 
the  FPU  to  main  memory.  Here  the  68030  must  wait  until  the  68881  has 
finished  making  the  data  available. 

The  syntax  of  the  instructions  follows  the  same  rules  already  familiar  to 
the  68000  series  processors.  By  now  most  assemblers  on  the  Amiga  can 
process  68030  and  68881  instructions. 
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All  FPU  instructions  begin  with  the  letter  "F"  (as  all  PMMU  instructions 
begin  with  "P"),  to  distinguish  them  from  those  of  the  main  processor. 

The  registers  are  designated  as  follows: 

•       FPO  -  FP7  for  the  eight  floating-point  data  registers 

FPCR,  FPSR  and  FPIAR  for  the  control  registers  (in  general  FPcr) 

The  following  abbreviations  are  valid  for  the  various  data  types: 

.B,  .W,  .L 

for  byte,  word  or  long  word  integer 

.S,  .D 

for  single  or  double  precision  real 

X     for  extended  precision  real 

•P     for  packed  decimal 

All  the  same  addressing  modes  can  be  used  as  for  the  68030,  except  in 
the  few  instructions  that  permit  only  certain  kinds  of  addressing.  The 
syntax  is  also  the  same. 

Data  Transfer  Instructions 


Instruction  Syntax 

Operand  Format 

Operand 

Operation 

FMOVE 

FPmm.FPn 

X 

Source->dest 

<ea>,FPn 

B.W.L.S.D.X.P 

FPm,<ea> 

B.W.L.S.D.X 

FPm,<ea>(#k) 

P 

FPm,<ea>(Dn) 

P 

<ea>,FPcr 

L 

FPcr,<ea> 

L 

FMOVECR 

#ccc,FPn 

X 

ROM  constant  ->  FPn 

FMOVEM 

<ea>,<list> 

L,X 

Register  list  ->  dest 

<ea>,Dn 

X 

<list>,<ea> 

ux 

Source  ->  register  list 

Dn,<ea> 

X 

Remarks: 

The  FMOVE  instruction  with  .P  (packed  decimal)  as  the  destination 
format  can  automatically  round  to  a  desired  number  of  places.  The 
rounding  value,  which  can  be  supplied  immediately  or  in  a  data  register, 
is  specified  as  follows: 
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-64  <=  k  <=  0        Rounded  to  Ikl  places  after  the  decimal  point 

0  <  k  <=  17  Mantissa  is  rounded  to  k  places  independent  of  the 

exponent 


In  the  FMOVECR  instruction,  "ccc' 
constant  from  the  ROM  of  the  FPU: 


is  the  number  of  a  numerical 


Number 

Constant 

$00 

PI 

$0B 

Log !  0(2) 

$oc 

e 

$0D 

Log2(e) 

$0E 

Log10(e) 

$0F 

0.0 

$30 

ln(2) 

$31 

ln(10) 

$32 

10° 

to 

101,102, 104, . 

. 102048 

$3F 

104096 

MOVEM  transfers  any  combination  of  the  eight  data  registers  or  one  of 
the  three  control  registers  between  memory  and  the  FPU.  If  the  list  is  in  a 
processor  data  register,  only  a  data  register  transfer  is  possible.  The 
following  format  applies: 


Type  of  addressing 
Predecrement  -(An) 
All  others 

Bit  7 
FP7 
FP0 

■-- 

BitO 
FP0 
FP7 

Dyadic  Operations 

Dyadic  operations  are  functions  performed  on  two  operands,  for  example 
multiplication  or  addition.  The  first  operand  can  be  addressed  with  any 
addressing  method,  the  second  must  always  be  one  of  the  FPU  data 
registers.  The  result  of  the  function  will  be  placed  in  this  data  register. 


Instruction 

Function 

FADD 

Add 

FCMP 
FDIV 

Compare 
Divide 

FMOD 

Modulo 

FMUL 
FREM 

Multiply 
IEEE  remainder 

FSCALE 
FSGLDIV 

FSGLMUL 
FSUB 

Exponent  scaling 
Divide  (single  precision) 
Multiply  (single  precision) 
Subtract 
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Remarks: 

FSCALE  adds  the  first  value  (whose  fractional  places  are  truncated)  to 
the  exponent  of  the  second. 

FREM  delivers  the  remainder  of  a  division  according  to  the  IEEE- 
definition: 


IN  I  (Operandi  /  Operandi)  rounded  with  'round-to-nearest'! 
Operand2  -  (Operandi  *  X) 


Monadic  Operations 

A  monadic  operation  is  a  function  performed  on  a  single  operand.  The 
operand  can  be  referenced  with  any  addressing  method.  The  result  is 
always  placed  in  an  FPU  data  register. 


Instruction 

Function 

FABS 

Absolute  value 

FACOS 

Arccosine 

FASIN 

Arcsine 

FATAN 

Arctangent 

FATANH 

Hyperbolic  arctangent 

FCOS 

Cosine 

FCOSH 

Hyperbolic  cosine 

FETOX 

e  to  the  x 

FETOXM1 

e  to  the  x-1 

FGETEXP 

Get  exponent 

FGETMAN 

Get  mantissa 

FINT 

Integer 

FINTRZ 

Integer  round  to  zero 

FLOGN 

Logarithm  of  (x) 

FLOGNP1 

Logarithm  of  (x+1 ) 

FLOG10 

Log  base  1 0  of  x 

FLOG2 

Log  base  2  of  x 

FNEG 

Negate 

FSIN 

Sine 

FSINH 

Hyperbolic  sine 

FSQRT 

Square  root 

FTAN 

Tangent 

FTANH 

Hyperbolic  tangent 

FTENTOX 

10Ax 

FTWOTOX 

2Ax 

Instruction        Syntax 


Format 


Instruction 


FSINCOS 


<ea>,FPc:FPs 
FPm,FPc:FPs 


B.W.L.S.D.X.P 
X 


SIN(source)  ->  FPs; 
COS(source)  ->  FPc 
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Remarks: 

FSINCOS  produces  two  results,  which  are  placed  in  separate  data 
registers. 

The  unit  of  measurement  of  angles  in  trigonometric  functions  is  the 

radian. 

Program  Control  Instructions 

This  group  of  instructions  allows  control  of  program  flow  by  using 
condition  codes  generated  by  the  FPU.  Their  functions  correspond  to  the 
68030  instructions  of  the  same  name. 


Instruction 

Operand  Syntax 

Operand  Format/Size 

Operation 

FBcc 

<Label> 

W,L 

If  true,  then  PC+d->PC 

FDBcc 

Dn,<Label> 

W 

If  true,  then  no 
operation,  else  Dn-1- 
>Dn;  If  Dn  o  -1  then 
PC+d->PC 

FNOP 

None 

None 

No  operation 

FScc 

<ea> 

B 

If  true,  then  1's->dest 
else  0's->dest 

FTST 

<ea> 

B,W,L,S,D,X,P 

FPSR  Set  cond.codes 

FPn 

X 

The  following  mnemonics  can  be  given  for  "cc": 
With  Exception  (NAN  bit  set  in  Status  Register): 


GE 

greater  or  equal 

GL 

greater  or  less 

GLE 

greater,  less  or  equal 

GT 

greater 

LE 

less  or  equal 

LT 

less 

NGE 

not  (greater  or  equal) 

NGL 

not  (greater  or  less) 

NGLE 

not  (greater,  less  or  equal) 

NGT 

not  (greater) 

NLE 

not  (less  or  equal) 

NLT 

not  less 

SEQ 

equal 

SNE 

unequal 

SF 

always  false 

ST 

always  true 
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Without  Exception: 


OGE 

ordered  and  greater  or  equal 

OGL 

ordered  and  greater  or  less 

OR 

ordered 

OGT 

ordered  and  greater 

OLE 

ordered  and  less  or  equal 

OLT 

ordered  less 

UGE 

unordered  or  greater  or  equal 

UEQ 

unordered  or  equal 

UN 

unordered 

UGT 

unordered  or  greater 

ULE 

unordered  or  less  or  equal 

ULT 

unordered  or  less 

EQ 

equal 

NE 

unequal 

F 

always  false 

T 

always  true 

This  list  may  seem  confusing  if  you're  used  to  the  68030  condition  codes. 
What  does  ordered  mean?  Why  is  there  a  distinction  between  "greater  or 
less"  and  "unequal"? 

The  reason  is  that  a  floating-point  number  can  represent  two  special 
conditions  that  a  normal  number  cannot: 


1 .  +  or  -  infinity 

2.  not-a-number  (NAN) 


A  number  with  all  l's  in  the  exponent  and  all  0's  in  the  mantissa 
represents  an  infinity.  The  sign  bit  remains  valid,  so  there  are  both  plus 
and  minus  infinities. 

An  infinity  is  produced  when  the  exponent  of  a  result  is  greater  than  or 
equal  to  the  greatest  possible  exponent  that  can  be  represented. 

An  invalid  number  (not-a-number)  occurs  when  the  exponent  is  all  l's 
and  the  mantissa  is  not  all  0's.  This  can  arise  through  a  number  of  invalid 
operations,  such  as  applying  the  square  root  function  to  a  negative 
number  or  dividing  two  infinities. 

A  NAN  can  also  be  used  to  signal  user-defined  exception  conditions. 
This  is  the  purpose  of  the  SNAN  exception  (signaling  Not-A-Number), 
which  occurs  when  a  function  is  called  with  a  "signaling"  NAN  as  an 
operand.  This  intentionally  supplied  NAN  is  identified  by  a  zero  bit  in  the 
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first  fractional  position  of  the  mantissa.  If  the  FPU  produces  a  NAN  as  the 
result  of  a  computation,  it  sets  this  bit,  even  if  it  was  called  with  a 
signaling  NAN  (assuming  the  SNAN  exception  has  been  disabled). 

The  NAN  presents  a  few  problems  in  the  handling  of  condition  codes. 
Whereas  plus  infinity  can  be  said  to  be  greater  than  any  natural  number, 
this  concept  of  comparison  is  not  possible  with  a  NAN.  Is  the  number  1 
greater  or  less  than  a  NAN?  There  is  no  answer  to  this  question.  For  this 
reason,  in  addition  to  greater,  less  and  equal,  the  conditions  ordered  and 
unordered  have  been  introduced.  The  unordered  condition  applies  when 
the  NAN  bit  in  the  Condition  Code  Register  is  set.  All  comparisons 
testing  for  greater  or  less  check  the  NAN  bit.  If  it  is  set,  the  first  number  is 
neither  greater  nor  less  than  the  second.  Moreover,  the  numbers  are  not 
equal,  either.  Rather,  they  are  unordered,  and  this  is  the  only  condition 
that  will  test  true  in  such  a  case. 

Only  the  conditions  equal  and  not  equal  (EQ  and  NE)  function  the  same 
as  they  do  for  integers  in  the  68030. 

So  that  an  additional  branch  instruction  is  not  required  to  intercept  the 
NAN  condition,  the  68881  has  a  built-in  BSUN  exception.  If  you  use  one 
of  the  instructions  from  the  previous  first  list  and  allow  this  exception, 
the  68030  executes  the  exception  procedure  as  soon  as  the  NAN  bit  is 
set  at  the  branch. 

An  important  reminder:  "not  less"  doesn't  always  mean  "greater";  it 
could  mean  "unordered". 

System  Control  Instructions 

This  group  consists  of  only  three  instructions: 

FSAVE  and  FRESTORE  cause  the  operating  system  to  save  and  restore 
the  internal  state  of  the  FPU  and  are  mainly  used  when  switching 
between  two  tasks,  both  of  which  want  FPU  access. 

An  FSAVE  and  subsequent  MOVEM  for  all  11  registers  preserves  the 
momentary  state  of  the  FPU  entirely,  even  if  it  was  interrupted  in  the 
middle  of  a  computation.  (In  this  case  the  FSAVE  transfers  184  bytes.) 
Any  other  FPU  operation  can  now  be  allowed  to  execute,  until,  by  means 
of  the  reverse  MOVEM  and  FRESTORE,  the  FPU  is  restored  to  its  earlier 
state  and  can  resume  the  interrupted  computation. 
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With  FTRAPcc  an  exception  can  be  generated  regardless  of  condition 
code.  A  word  or  long  word  given  with  the  FTRAPcc  instruction  is 
considered  to  be  surrendered  to  the  trap  handler  and  will  not  be  handled 
by  the  processor. 


Instruction 

Operand  Syntax 

Operand  Size 

Operation 

FRESTORE 

<ea> 

None 

State  frame  ->  internal 
register 

FSAVE 

<ea> 

None 

Internal  register  ->  state 
frame 

FTRAPcc 

None 

None 

If  condition  true,  then 
exception 

#xxx 

W,L 

The  FPU  Exceptions 

As  previously  mentioned,  there  are  eight  exception  types  that  can  be 
generated  by  the  FPU: 


BSUN 

Branch  /  Set  On  Unordered 

SNAN 

Signaling  Not  A  Number 

OPERR 

OPerand  ERRor 

OVFL 

OVerFLow 

UNFL 

UNderFLow 

DZ 

Divide  by  Zero 

INEX2 

INEXact  Operation 

INEX1 

INEXact  decimal  input 

BSUN  has  the  highest  priority  and  INEX2/1  the  lowest  priority.  If 
multiple  exceptions  occur  simultaneously,  the  68030  executes  the  one 
with  the  highest  priority,  and  the  trap  handler  must  worry  about  whether 
lower  priority  bits  are  also  set. 

The  individual  FPU  exceptions  are  assigned  to  the  following  TRAP 
vectors  on  the  68030: 
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Vector  Number 

Vector  Offset 

Assignment 

7 

$01C 

FTRAPcc  instruction 

11 

$02C 

F-Line  emulator 

13 

$034 

Protocol  violation 

48 

$0C0 

BSUN 

49 

$0C4 

Inexact  result 

50 

$0C8 

Divide  by  zero 

51 

$0CC 

Underflow 

52 

$0D0 

Operand  error 

53 

$0D4 

Overflow 

54 

$0D8 

SNAN 

FTRAPcc  This  exception  is  called  if  condition  cc  is  valid  on  an 

FTRAP  instruction. 


F-Line 


Cop.Prot. 


BSUN 


INEX 


This  exception  indicates  that  an  invalid  FPU  instruction 
was  detected.  The  bit  pattern  of  the  current  instruction 
does  not  match  any  known  instruction. 

A  protocol  violation  in  the  communication  between 
main  and  coprocessor  generates  this  exception.  The 
cause  is  usually  a  hardware  defect. 

As  described  in  the  last  section,  this  exception  occurs 
on  certain  branch  conditions  (also  FTRAPcc,  etc.),  when 
the  NAN  bit  in  the  Condition  Code  Register  is  set.  The 
NAN  bit  must  be  reset  within  the  trap  routine,  because 
at  the  conclusion  of  exception  handling  the  FPU  calls 
the  instruction  again. 

There  are  two  potential  generators  of  an  Inexact  Result 
Exception:  INEX1  is  produced  when  a  packed  decimal 
number  is  converted  internally  to  extended  precision 
format. 


INEX2 


DZ 


Indicates  the  need  for  rounding  in  all  other 
circumstances.  All  operations  resulting  in  periodic  or 
nonteiminating  binary  numbers  produce  this  exception. 

A  Divide-by-zero  occurs  upon  dividing  a  number  by 
zero  or  calling  a  transcendental  function  that  has  a 
perpendicular  asymptote  at  this  position,  so  that  F(X) 
goes  to  infinity  (e.g.,  tan(PI/2)). 
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If  this  exception  is  disabled,  the  FPU  returns  an  infinity 
result. 


UNFL 


OPERR 


The  Underflow  exception  is  called  when  the  result  of  a 
computation  is  too  small  to  be  represented  internally, 
meaning  the  exponent  is  less  than  or  equal  to  the  least 
possible  value. 

It  also  occurs  when  a  MOVE  instruction  converts  an 
operand  from  extended  precision  to  single  or  double, 
and  the  exponent  is  less  than  or  equal  to  the  least 
possible  value. 

Conversion  to  .B,  .W  or  .L  format  does  not  cause  an 
Underflow  exception,  but  simply  returns  a  zero  value. 

Despite  the  trap,  in  all  Underflows,  either  the  least 
possible  result  or  zero  is  returned,  depending  on 
rounding  mode. 

Operand  Error  refers  to  a  variety  of  possible  error 
conditions  arising  from  the  use  of  mathematical 
functions  with  inappropriate  input  or  in  a  context  that 
does  not  have  a  valid  mathematical  interpretation. 
Square  root  of  a  negative  number  is  an  example  of  such 
a  condition. 


OVFL 


SNAN 


The  same  conditions  apply  to  the  Overflow  exception 
as  to  Underflow,  except  that  it  is  activated  by  the 
greatest  possible  exponent,  and  returns  infinity  or  the 
greatest  possible  result,  again  depending  on  the 
rounding  mode. 

This  exception  is  called  when  an  operand  of  a  monadic 
or  dyadic  function  is  a  signaling  NAN. 


Because  the  main  processor  and  the  math  coprocessor  work  in  parallel, 
the  FPU  exceptions  are  not  recognized  by  the  68030  until  it  has  already 
processed  subsequent  instructions  and  arrived  at  the  next  FPU 
command.  A  trap  handler  whose  job  is  to  redress  an  FPU  error  would  like 
to  know  which  instruction  caused  it.  But  the  68030  has  already  gone 
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ahead  in  the  program,  and  the  last  address  it  has  placed  on  the  stack  is 
the  next  FPU  instruction.  Between  this  and  the  one  that  caused  the 
exception  is  an  unknown  number  of  normal  processor  instructions. 

The  FPIAR  Register  (Floating  Point  Instruction  Address  Register)  is 
designed  to  take  care  of  this  problem.  It  holds  the  address  of  the  FPU 
instruction  that  the  coprocessor  is  currently  processing.  If  an  exception 
occurs,  the  trap  handler  only  needs  to  read  the  address  from  the  FPIAR 
Register  to  find  the  offending  instruction  in  main  memory. 

11.2.3        Differences  Between  the  MC  68881  and 
68882 

The  essential  difference  between  the  two  floating-point  coprocessors  is 
in  the  manufacturing  technology.  Whereas  the  maximum  cycle  rate  for 
the  68881  was  20  MHz,  the  fastest  version  of  the  68882  manages  50 
MHz.  But  the  68882's  advantage  in  speed  results  not  only  from  a  higher 
cycle  frequency.  Even  at  the  same  frequency  it  runs  25%  faster  than  the 
'881.  This  effect  is  linked  to  the  improved  facility  for  parallel  processing. 
Both  coprocessors  have  only  a  single  APU,  and  can  perform  only  one 
floating-point  computation  at  a  time.  The  fetching  of  new  operands  and 
conversion  of  numeric  formats  runs  parallel  to  the  work  of  the  APU. 
Here's  an  example  of  programming  that  maximizes  the  efficiency  of  the 
68882: 

When  the  following  loop: 


FMOVE.X  (A0),EP1 
FADD.X  (A1),FP1 
FMOVE.X  FP1, (A2) 


Fetch  next  entry 
Add 
Store 


is  optimized  for  the  68882  it  looks  like  this: 


FMOVE.X  (A0),FP1 
FMOVE.X  (A3),FP2 
FADD.X  (A1),FP1 
FADD.X  (A4),FP2 
FADD.X  FP1, (A2) 
FMOVE.X  FP2, (A3) 


Fetch  next  entry 
Fetch  next  +  1 
First  add 
Add  next  +  1 
Store  first  result 
Store  next  +1 


This  simple  example  shows  how  the  placement  of  instructions  within  a 
loop  can  help  alleviate  register  conflict. 
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To  do  this,  try  to  combine  the  fastest  FMOVE's  with  the  fastest  arithmetic 
instructions,  and  the  slowest  FMOVE's  with  the  slowest  arithmetic 
instructions. 


11.2.4        Cache  Memory 


The  68030  has  two  internal  caches:  256  bytes  each  for  instructions  and 
data.  Their  function  is  to  store  frequently  used  values  and  make  them 
available  to  the  CPU  without  wait  time  on  subsequent  references. 

This  solves  the  problem  of  designing  a  main  memory  that  is  both  large 
and  fast.  Because  of  caching,  sufficient  speed  is  attained  with  less 
expensive  dynamic  RAM,  so  you  don't  have  to  skimp  on  memory  size. 

RAM  access  requires  wait  cycles,  which  inevitably  results  in  wasting 
some  of  the  maximum  processor  speed.  But  wait  time  can  be  significantly 
reduced  by  reading  a  large  part  of  the  data  and  instructions  from  main 
memory  only  the  first  time  they  are  referenced  and  then  reading  them 
from  cache  memory.  Depending  on  the  program,  efficiency  increases  of 
up  to  100%  are  possible. 

The  caching  concept  exploits  the  fact  that,  during  program  processing, 
the  CPU  spends  most  of  its  time  in  loops  of  no  more  than  10  to  30 
instructions.  Once  such  a  loop  has  executed  the  first  time,  it  is  fully 
contained  in  the  instruction  cache  and  need  not  be  read  again  from  main 
memory. 

This  principle  also  applies  to  data.  The  most  frequently  referenced 
addresses  tend  to  be  localized.  For  example,  if  you  look  at  a  typical  C 
program,  you'll  see  that  within  a  function,  most  data  accesses  refer  to  the 
local  variables,  which  are  placed  on  the  stack  in  a  single  block. 

Instruction  Cache  Design 

Each  cache  in  the  68030  consists  of  16  rows,  each  of  which  contains 
four  long  words.  Each  row  is  assigned  a  tag-entry,  in  which  the  address 
(bits  8  -  31)  and  the  FC2  bit  of  the  function  code  (for  distinguishing 
between  supervisor  and  user  mode)  is  placed.  The  tag-entry  also  contains 
four  Valid  bits,  for  the  four  long  words. 
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Address  bits  4-7  select  the  cache  row,  and  bits  2  and  3  select  one  of  the 
long  words.  When  the  CPU  accesses  main  memory,  a  row  is  selected  by 
the  appropriate  address  bits  and  the  row's  tag-entry  is  compared  with 
address  bits  8  -  31  and  the  FC2  bit.  If  they  agree,  and  if  the  Valid  bit  for 
the  desired  long  word  is  set,  the  condition  is  called  a  cache-hit.  In  this 
case,  the  value  can  be  read  from  the  cache  and  RAM  is  not  accessed. 

A  cache-miss  occurs  when  the  tag  and  address  do  not  agree  or  the  Valid 
bit  is  zero. 

If  just  the  Valid  bit  is  missing,  the  CPU  reads  the  value  from  main  memory, 
transfers  it  to  the  cache  and  sets  the  Valid  bit.  If  there  was  no  tag-entry 
agreement,  the  CPU  tries  not  only  to  retrieve  the  desired  long  word  from 
RAM,  but  also  to  fill  the  entire  row.  A  burst-fill  is  started  for  this  purpose. 
The  burst-fill  takes  advantage  of  the  fact  that  the  four  long  words 
occupy  consecutive  addresses  in  memory.  A  special  access  method  of 
dynamic  RAM  enables  extremely  fast  referencing  of  sequential  data.  A 
burst-fill  for  four  long  words  barely  takes  longer  than  two  normal 
accesses. 

After  a  successful  burst,  the  address  is  entered  to  the  tag-field  and  all  four 
Valid  bits  are  set.  Accessing  this  data  again  results  in  a  cache-hit. 

Function  of  Address  bits  in  Cache: 


Address 

Function 

A0&A1 

Byte  within  long  word 

A2&A3 

Long  word  within  row 

A4-A7 

Row  number 

A8  -  A31 

Address  of  data  in  corresponding  row 

&FC2 

(stored  in  tag-entry  of  row) 

Cache  Row  Layout: 


Tag  (FC2.A31  -  A8)|Longword  0|Longword  1|Longword  2|Lw3 


The  data  Cache 

The  data  cache  differs  from  the  instruction  cache  in  its  additional 
requirement  for  write  access.  Write  access  is  not  relevant  to  instruction 
caching,  since  instructions  are  not  altered.  Also,  data  cache  tag-entries 
contain  all  three  function  code  bits  because  the  data  and  program 
regions  must  be  distinguished. 
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Basically  the  data  cache  is  designed  as  a  write-through  cache.  This 
means  that  all  data  is  written  to  main  memory,  regardless  of  whether  or 
not  it  is  present  in  the  cache.  Thus  values  in  RAM  are  always  valid. 

Two  modes  are  available  for  transferring  written  data  to  the  cache:  with 
or  without  Write  Allocation  (WA).  Without  Write  Allocation,  a  value  is 
transferred  to  the  cache  only  when  it  was  already  found  there  (i.e.,  when 
a  cache-hit  occurred).  The  new  value  replaces  the  old,  without  any 
change  to  the  tag-entry  or  Valid  bits.  In  this  mode,  values  with  new  tag- 
addresses  are  written  to  the  cache  only  on  read  accesses. 

With  Write  Allocation,  all  data  is  transferred,  regardless  of  whether  a 
cache-hit  or  a  cache-miss  occurred.  A  miss  clears  the  Valid  bits  of  the 
remaining  three  long  words.  WA  mode  is  necessary  if  both  supervisor 
and  user  access  are  permitted  at  the  same  address,  as  is  the  case  in  the 
Amiga.  The  following  example  should  help  illustrate  the  problem  without 
Write  Allocation: 

•  The  supervisor  reads  Value  A  at  Location  X,  and  A  is  loaded  to  the 
cache. 

•  The  user  program  writes  Value  B  to  Location  X.  Since  the  cache 
distinguishes  user  from  supervisor  access,  no  hit  occurs  despite  the 
same  address.  B  is  not  transferred  to  the  cache,  but  remains  at 
Location  X. 

•  The  supervisor  reads  Location  X  again,  but  getting  a  hit,  it  reads  it 
from  the  cache.  It  reads  the  wrong  value  (A  instead  of  B). 

The  Cache  Control  Registers  (CACR  and  CAAR) 

Two  registers  control  the  functioning  of  both  caches.  The  Cache  Control 
Register  (CACR)  contains  several  control  bits,  while  the  Cache  Address 
Register  (CAAR)  specifies  the  address  of  a  long  word  in  the  cache.  This 
address  is  necessary  for  clearing  individual  entries  in  the  cache.  The 
CAAR  layout  corresponds  to  the  addressing  of  the  individual  cache 
entries  in  normal  operation: 
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Cache  Address  Register  (CAAR) 


BitNr.: 

31  ...8 

7  ...  4               3  and  2 

1  andO 

Function: 

|  Unused 

|  Cache  row    |  Long  word 

|   Unused 

Cache  Control  Register  (CACR) 


BitNr.: 

Name: 

Function: 

31  -14 

— 

Unused 

13 

WA 

Write  Allocate 

12 

DBE 

Data  Burst  Enable 

11 

CD 

Clear  Data  Cache 

10 

CED 

Clear  Entry  in  Data  Cache 

9 

FD 

Freeze  Data  Cache 

8 

ED 

Enable  Data  Cache 

7-5 

— 

Unused 

4 

IBE 

Instruction  Burst  Enable 

3 

CI 

Clear  Instruction  Cache 

2 

CEI 

Clear  Entry  in  Instruction  Cache 

1 

Fl 

Freeze  Instruction  Cache 

0 

El 

Enable  Instruction  Cache 

WA  Write  Allocation  mode  is  turned  on  if  this  bit  is  set. 

DBE  Enables  burst  on  cache-miss  with  wrong  tag-entry. 

CD  All  entries  in  the  data  cache  are  cleared  when  a  1  is  written  to 

this  bit.  This  only  happens  once;  the  CD  bit  is  not  stored. 

CED  Clears  only  the  cache-entry  whose  address  is  in  the  CAAR. 

FD  Freezes  the  data  cache.  Subsequent  read  accesses  without 

cache-hits  do  not  overwrite  old  values.  Cache  contents  are 
modified  by  write  accesses  only. 

The  FD  bit  is  useful  for  optimizing  program  speed.  It  prevents 
one-time  accesses  (for  which  the  cache  provides  no  speed 
advantage)  from  destroying  useful  values  in  the  cache. 

ED  The  processor  ignores  a  cache-hit  if  the  Enable  bit  is  cleared. 

All  data  is  retrieved  from  main  memory.  The  cache  contents 
continue  to  be  updated  and  can  be  used  as  soon  as  caching 
is  enabled. 

IBE  Enables  burst  access  for  instruction  cache. 
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CI  Clears  all  instruction  cache  entries. 

CEC  Clears  the  entry  whose  address  is  in  the  CAAR. 

FI  If  the  FI  bit  is  set,  the  contents  of  the  instruction  cache  cease 

to  be  updated. 

EI  If  the  EI  bit  is  zero,  a  cache-hit  is  ignored  and  all  instructions 

are  fetched  from  main  memory. 
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11.3  The  CIA  8520 


The  8520  CIA 

GND-»C 

1  V           J              40 

2  V_^                39 

^**CNT 

?MM-tCZ 

3*»SP 

PA1.  .1 

3                                                 38 

Z3*-A0 

„,-,.  .i 

4                                                 37 

Z3«-A1 

mil  rf*~ 

5                                                 36I3«-A2 

PA4*-»cn 

6                                                 35 

=1— £?_ 

PA5«-»^ 

7  Q                  34 

8  >-*                  33 

3*-RES 

pa6«-»c: 

^•**D0 

PA7**^ 

9  r\J                  32 

10  >>*                 31 

Z3-**D1 

PB0«-»CZ 

^♦-»D2 

PB1«-HZZ 
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17                                              24 

Z3«-FLAO 
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20                                              21 
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Note:  The  arrows  show  the  direction  of  the  signal. 

A  line  above  a  signal  names  means  the 

signal  is  active  when  low  (0  =  active). 

77i<?  CM  S520 

The  8520  is  a  peripheral  component  of  the  Complex  Interface  Adapter 
(CIA)  class,  which  basically  means  that  its  developers  tried  to  support  as 
many  functions  as  possible  on  a  single  chip.  A  close  inspection  of  the 
8520  reveals  great  similarity  to  its  old  counterpart  in  the  C64,  namely  the 
6526.  Only  the  functioning  of  registers  8  through  11  has  changed 
slightly.  This  is  certainly  good  news  for  anyone  familiar  with 
programming  the  6526. 

The  8520  has  the  following  features:  two  freely  programmable  8-bit 
parallel  ports  (PA  and  PB),  two  16-bit  timers  (A  and  B),  a  bi-directional 
serial  port  (SP)  and  a  24-bit  counter  (event  counter)  with  an  alarm 
function  upon  reaching  a  programmed  value.  All  functions  can  generate 
interrupts. 

The  functions  of  the  8520  are  organized  into  16  registers.  To  the 
processor  they  look  like  ordinary  memory  locations,  since  all  peripheral 
components  in  a  68  x  0  system  are  memory  mapped  and  can  be  read  and 
written  with  the  usual  MOVEs  and  other  processor  instructions. 
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The  16  internal  registers  are  selected  with  the  four  address-inputs,  A0-A3. 
Details  about  the  integration  of  the  CIA  into  the  Amiga  system  are  found 
at  the  end  of  this  section. 

The  following  are  the  functions  of  the  16  registers  (actually  15,  since 
register  1 1  ($B)  is  unused): 


The  8520  registers 


Register 

Name 

Function 

0 

0 

PRA 

Port  A  data  register 

1 

1 

PRB 

Port  B  data  register 

2 

2 

DDRA 

Port  A  data  direction  register 

3 

3 

DDRB 

Port  B  data  direction  register 

4 

4 

TALO 

Timer  A  lower  8  bits 

5 

5 

TAHI 

Timer  A  upper  8  bits 

6 

6 

TBLO 

Timer  B  lower  8  bits 

7 

7 

TBHI 

Timer  B  upper  8  bits 

8 

8 

Event  low 

Counter  bits  0-7 

9 

9 

Event  mid 

Counter  bits  8-1 5 

10 

A 

Event  high 

Counter  bits  16-23 

11 

B 

— 

Unused 

12 

C 

SP 

Serial  port  data  register 

13 

D 

ICR 

Interrupt  control  register 

14 

E 

CRA 

Control  register  A 

15 

F 

CRB 

Control  register  B 

The  parallel  ports 


Register 

Name 

D7 

D6 

D5 

D4 

D3 

D2 

D1 

DO 

0 
1 
2 
3 

PRA 
PRB 
DDRA 
DDRB 

PA7 
PB7 
DPA7 
DPB7 

PAS 
PB6 
DPA6 
DPB6 

PA5 
PB5 
DPA5 
DPB5 

PA4 
B4 

DPA4 
DPB4 

PA3 
PB3 
DPA3 
DPB3 

PA2 
PB2 
DPA2 
DPB2 

PA1 
PB1 
DPA1 
DPB1 

PAO 
PBO 
DPAO 
DPBO 

The  8520  has  two  8-bit  parallel  ports,  PA  and  PB,  each  of  which  is 
assigned  a  data  register,  PRA  (Port  Register  A)  and  PRB  (Port  Register 
B).  Associated  with  these  registers  are  the  chip's  16  port  lines,  PA0-PA7 
and  PB0-PB7.  The  8520  allows  the  data  direction  of  each  port  line  to  be 
individually  controlled.  This  means  that  each  port  line  can  be  used  as 
input  as  well  as  output.  For  this  purpose,  each  port  has  a  data  direction 
register,  DDRA  and  DDRB.  If  a  bit  in  a  data  direction  register  is  0,  its 
corresponding  line  behaves  as  input,  so  that  the  level  of  the  signal  on  this 
line  can  be  interrogated  by  reading  the  appropriate  bit  of  the  data 
register. 
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If  the  bit  is  set  to  1 ,  the  line  becomes  an  output.  Now  the  signal  on  the 
line  is  actually  determined  by  the  value  of  the  corresponding  bit  in  the 
data  register. 

In  general,  writing  to  a  data  register  always  stores  the  value  in  it,  while 
reading  always  returns  the  states  of  the  port  lines.  The  bits  in  the  data 
direction  register  determine  whether  the  value  of  the  data  register  is 
placed  on  the  port  lines.  Therefore  when  reading  a  port  that  is  configured 
as  an  output,  the  contents  of  the  data  register  are  returned,  while  when 
writing  to  an  input  port,  the  value  is  stored  in  the  data  register,  but  does 
not  appear  on  the  port  lines  until  the  port  is  configured  as  output. 
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8520  -  block  diagram 
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8520  access  control 


R/W    $2   CS    A3    A2     Al    AO    RES 


Key: 
I          | 

=  8-bit  line 
=  1 -bit  line 

Block  Diagram  of  the  8520  CIA 

To  simplify  data  transfer  through  the  parallel  ports,  the  8520  has  two 
handshake  lines,  PC  and  FLAG. 

The  PC  output  goes  low  for  one  clock  cycle  on  each  access  to  data 
register  B  (PRB,  reg.  1).  The  FLAG  input  responds  to  such  downward 
transitions.  Every  time  the  state  of  the  FLAG  line  changes  from  1  to  0,  the 
FLAG  bit  is  set  in  the  Interrupt  Control  Register  (ICR,  reg.  $D).  These 
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two  lines  allow  a  simple  form  of  handshaking  in  which  the  FLAG  and  PC 
lines  of  two  CIAs  are  cross-connected. 

The  sender  need  only  write  its  data  to  the  port  register  and  then  wait  for 
a  FLAG  signal  before  sending  each  additional  byte.  Since  FLAG  can 
generate  an  interrupt,  the  sender  can  even  perform  other  tasks  while  it  is 
waiting.  The  same  applies  to  the  receiver,  except  that  it  reads  the  data 
from  the  port  instead  of  writing  it. 

The  timers: 

Read  access: 


Register 

Name 

D7 

DS 

D5 

D4 

D3 

D2 

D1 

DO 

4 
5 
6 

7 

TALO 

TAHI 

TBLO 

TBHI 

TAL7 
TAH7 
TBL7 
TBH7 

TAL6 
TAH6 
TBL6 
TBH6 

TAL5 
TAH5 
TBL5 
TBH5 

TAL4 
TAH4 
TBL4 
TBH4 

TAL3 
TAH3 
TBL3 
TBH3 

TAL2 
TAH2 
TBL2 
TBH2 

TAL1 
TAH1 
TBL1 
TBH1 

TALO 
TAHO 
TBLO 
TBHO 

Write  access: 


Register 

Name 

D7 

D6 

D5 

D4 

D3 

D2 

D1 

DO 

4 
5 
6 

7 

PALO 
PAHl 
PBLO 
PBHI 

PAL7 
PAH7 
PBL7 
PBH7 

PAL6 
PAH6 
PBL6 
PBH6 

PAL5 
PAH5 
PBL5 
PBH5 

PAL4 
PAH4 
PBL4 
PBH4 

PAL3 
PAH3 
PBL3 
PBH3 

PAL2 
PAH2 
PBL2 
PBH2 

PAL1 
PAH1 
PBL1 
PBH1 

PALO 
PAHO 
PBLO 
PBHO 

The  8520  has  two  16-bit  timers.  These  timers  can  count  from  a  preset 
value  down  to  zero.  A  number  of  modes  are  possible  and  can  be  selected 
through  a  control  register,  one  for  each  timer  (CRA  and  CRB). 

Each  timer  consists  internally  of  four  registers  (timer  A:  TALO+TAHI  and 
PALO+PAHI),  or  two  register  pairs,  since  each  low  and  high  register  pair 
forms  the  16-bit  timer  value.  Both  register  pairs  have  the  same  address, 
but  one  can  only  be  read  and  the  other  only  written.  On  a  write  access  to 
one  of  the  timer  registers  the  value  is  first  saved  in  a  latch,  then  loaded 
into  the  timer  register  and  decremented  until  the  timer  reaches  zero. 
When  this  happens,  the  value  is  loaded  from  the  latch  into  the  timer 
register  again. 

Reading  a  timer  register  returns  the  current  state  of  the  timer.  To  get  a 
correct  value,  though,  the  timer  must  be  stopped. 

The  following  example  shows  why: 
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Timer  state:  $0100. 

•  A  read  access  to  register  5  returns  the  high  byte  of  the  current  state: 
$01. 

Before  the  low  byte  (reg.  4)  can  be  read,  the  timer  is  decremented 
again  and  the  timer  state  is  now  $00FF. 

The  low  byte  is  read:  $FF. 

Resulting  timer  state:  $01FF. 

•  Instead  of  stopping  the  timer,  which  also  causes  problems  since  now 
timer  pulses  are  ignored,  a  better  method  can  be  used:  Read  the  high 
byte,  then  the  low  byte  and  then  the  high  byte  again.  If  the  two 
high  byte  values  match,  then  the  value  read  is  correct.  If  not,  the 
process  must  be  repeated. 

•  Which  signals  decrement  the  timers  is  determined  for  timer  A  by  bit 
5  and  for  timer  B  by  bits  5  and  6  of  the  respective  control  registers. 

Only  two  sources  are  possible  for  timer  A: 

1.  Timer  A  is  decremented  with  each  clock  cycle.  The  cycle  frequency 
of  the  CIAs  in  the  Amiga  is  716  KHz  (INMODE  =  0). 

2.  Timer  A  is  decremented  with  each  high  impulse  on  the  CNT  line 
(INMODE  =  1). 

Timer  B  has  four  input  modes: 

1.  Clock  cycles  (INMODE  bits  =  00)  (binary  -  the  first  digit  stands  for 
bit  6,  the  second  for  bit  5). 

2.  CNT  impulse  (INMODE  bits  =  01). 

3.  Timer  A  timeouts  (allows  two  timers  to  form  a  32-bit  timer) 
(INMODE  bits  =  10). 

4.  Timer  A  timeouts  when  the  CNT  line  is  high  (allows  the  length  of  a 
pulse  on  the  CNT  line  to  be  measured)  (INMODE  bits  =  11). 

The  timeouts  of  a  timer  are  registered  in  the  Interrupt  Control  Register 
(ICR).  When  timer  A  times  out,  the  TA  bit  (no.  0)  is  set,  while  when  timer 
B  times  out,  the  TB  bit  (no.  1)  is  set.  These  bits,  like  all  of  the  bits  in  the 
ICR,  remain  set  until  the  ICR  is  read. 
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In  addition,  it  is  also  possible  to  output  the  timeouts  to  parallel  port  B.  If 
the  PBon  bit  is  set  in  the  control  register  for  the  given  timer  (CRA  or 
CRB),  then  each  timeout  appears  on  the  appropriate  port  line  (PB6  for 
timer  A  and  PB7  for  timer  B). 

Two  output  modes  can  be  selected  with  the  OUTMODE  bit: 

OUTMODE  =  0     Pulse  mode 

Each  timeout  appears  as  a  positive  pulse  one  clock  period  long  on  the 
corresponding  port  line. 

OUTMODE  =  1     Toggle  mode 

Each  timeout  causes  the  corresponding  port  line  to  change  value  from 
high  to  low  or  low  to  high.  Each  time  the  timer  is  started  the  output  starts 
at  high. 

The  timers  are  started  and  stopped  with  the  START  bit  in  the  control 
registers.  START  =  0  stops  the  timer,  START  =  1  starts  it. 

The  RUNMODE  bit  selects  between  one-shot  mode  and  continuous 
mode.  In  one-shot  mode  the  timer  stops  after  each  timeout  and  sets  the 
START  bit  back  to  0.  In  continuous  mode  the  timer  restarts  after  each 
timeout. 

As  mentioned  before,  writing  to  a  timer  register  doesn't  write  the  value 
directly  to  the  register  but  to  a  latch  (also  called  a  prescaler,  since  the 
number  of  timeouts  per  second  is  equal  to  the  clock  frequency  divided 
by  the  value  in  the  prescaler).  There  are  several  ways  to  transfer  the 
value  from  the  latch  to  the  timer: 

1.  Set  the  LOAD  bit  in  the  control  register.  This  causes  a  forced  load, 
that  is,  the  value  in  the  latch  is  transferred  to  the  timer  registers 
regardless  of  the  timer  state.  The  LOAD  bit  is  called  a  strobe  bit, 
which  means  that  the  bit  is  not  stored  but  simply  triggers  a  one-time 
operation.  To  cause  another  forced  load,  a  1  must  be  written  to  the 
LOAD  bit  again. 

2.  Each  time  the  timer  runs  out,  it  is  automatically  reloaded  with  the 
value  in  the  latch. 
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3.  After  a  write  access  to  the  high  register  of  a  timer  that  is  stopped 
(START  =  0),  the  timer  is  automatically  loaded  with  the  value  in  the 
latch.  Therefore  the  low  byte  of  the  timer  should  always  be 
initialized  first. 


Assignment  of  the  bits  in  control  register  A: 


Register  No.  14/$E  Name:  CRA 
D7             D6                 D5 

D4 

D3 

D2 

D1 

DO 

not 

SPMODE 

INMUDfc 

LOAD 

RUNMODE 

OUT MODE 

PBon 

yiAHl 

used 

0=input 

0=clock 

1=force 

0=cont. 

0=pulse 

0=PB6off 

0=off         | 

1=output 

1=CNT 

load 
(strobe) 

"None- 
shot 

1=toggle 

1=PB6on 

1=on 

Assignment  of  the  bits  in  control  register  B: 


Register  No.  15/$F  Name:  CRB 

D7                    D6+D5 

D4 

D3 

D2 

D1 

DO 

ALARM 

INMODE 

LOAD 

RUNMODE 

OUTMODE 

PBon 

START 

0=TOD 

00=clock 

1=force 

0=cont. 

0=pulse 

0=PB7off 

0=off 

1=alarm 

01=CNT 
10=timerA 
11=timerA+ 
CNT 

load 
(strobe) 

None- 
shot 

1=toggle 

1=PB7on 

1=on 

The  event  counter: 


Register 
8  $8 


Name 
LSB  event 
Event  8-15 
MSB  event 


"D7- 

T7~ 

E15 

E23 


T3B~ 

"EB- 

E14 

E22 


TJ5 D4" D3~ 


"E5~" 
E13 
E21 


"E4- 
E12 
E20 


-E3~ 
E11 
E19 


"D2- 

"E2- 

E10 

E18 


ur 

"ET- 
E9 
E17 


TJrJ — | 

"ED- 
E8 
E16 


As  we  mentioned  earlier,  there  are  only  minor  differences  between  the 
8520  and  the  6526.  All  of  these  differences  concern  the  function  of 
registers  8-11.  The  6526  has  a  real-time  clock  which  returns  the  time  of 
day  in  hours,  minutes  and  seconds  in  the  individual  registers.  On  the 
8520  this  clock  is  replaced  by  a  simple  24-bit  counter,  called  an  event 
counter.  This  can  lead  to  some  confusion,  because  Commodore  often 
uses  the  old  designation  TOD  (Time-Of-Day)  when  referring  to  the  8520. 

The  operation  of  the  event  counter  is  simple.  It  is  a  24-bit  counter, 
meaning  that  it  can  count  from  0  to  16777215  ($FFFFFF).  With  each 
rising  edge  (transition  from  low  to  high)  on  the  TOD  line,  the  counter 
value  is  incremented  by  one.  When  the  counter  has  reached  $FFFFFF,  it 
starts  over  at  0  on  the  next  count  pulse.  The  counter  can  be  set  to  a 
defined  state  by  writing  the  desired  value  into  the  counter  registers. 
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Register  8  contains  bits  0-7  of  the  counter,  the  least  significant  byte 
(LSB),  in  register  9  are  bits  8-15,  and  in  register  10  are  bits  16-23,  the 
most  significant  byte  (MSB)  of  the  counter. 

The  counter  stops  on  each  write  access  so  that  no  errors  result  from  a 
sudden  carry  from  one  register  to  another  (as  described  in  the  timer 
discussion).  The  counter  starts  running  again  when  a  value  is  written  into 
the  LSB  (reg.  8).  Normally  the  counter  is  written  in  the  order:  register  10 
(MSB),  then  register  9,  and  finally  register  8  (LSB). 

To  prevent  carry  errors  when  the  counter  is  read,  the  counter  value  is 
written  into  a  latch  when  the  MSB  (reg.  10)  is  read.  Each  additional 
access  to  a  count  register  now  returns  the  value  of  the  latch,  which  can 
be  read  in  peace  while  the  counter  continues  to  run  internally.  The  latch 
is  turned  off  again  when  the  LSB  is  read.  The  counter  should  be  read  in 
the  same  order  as  it  is  written  (see  previous  paragraph). 

An  alarm  function  is  also  built  into  the  event  counter.  If  the  alarm  bit  (bit 
7)  is  set  to  1  in  control  register  B,  an  alarm  value  can  be  set  by  writing 
registers  8-10.  As  soon  as  the  value  of  the  counter  matches  this  alarm 
value,  the  alarm  bit  in  the  interrupt  control  register  is  set.  The  alarm  value 
can  only  be  set  -  a  read  access  to  registers  8-10  always  returns  the 
current  counter  state,  regardless  of  whether  or  not  the  alarm  bit  is  set  in 
control  register  B. 

The  serial  port 

Register        Name        D7        D6        D5        D4        D3        D2        PI       "W 


12  $C      |  SDR     |  57    |  56    |  55    |  54    |  53    |  S2    |  S1     |  SO 


The  serial  port  consists  of  the  serial  data  register  and  an  8-bit  shift  register 
that  cannot  be  accessed  directly.  The  port  can  be  configured  as  input 
(SPMODE=0)  or  output  (SPMODE=l)  with  the  SPMODE  bit  in  control 
register  A.  In  the  input  mode  the  serial  data  on  the  SP  line  are  shifted  into 
the  shift  register  on  each  rising  edge  on  the  CNT  line.  After  eight  CNT 
pulses  the  shift  register  is  full  and  its  contents  are  transferred  to  the  serial 
data  register.  At  the  same  time,  the  SP  bit  in  the  interrupt  control  register 
is  set.  If  more  CNT  pulses  occur,  the  data  continues  to  shift  into  the  shift 
register  until  it  is  full  again.  If  the  user  has  read  the  serial  data  register 
(SDR)  in  the  meantime,  the  new  value  is  copied  into  the  SDR  and  the 
transfer  continues  in  this  manner. 
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To  use  the  serial  port  as  output,  set  SPMODE  to  1.  The  timeout  rate  of 
timer  A,  which  must  be  operated  in  continuous  mode,  determines  the 
baud  rate  (number  of  bits  per  second).  The  data  are  always  shifted  out  of 
the  shift  register  at  half  the  timeout  rate  of  timer  A,  so  the  maximum 
output  rate  is  one  quarter  of  the  clock  frequency  of  the  8520. 

Transfer  begins  after  the  first  data  byte  is  written  to  the  SDR.  The  CIA 
transfers  the  data  byte  into  the  shift  register.  The  individual  data  bits  now 
appear  on  the  SP  line  at  half  the  timeout  rate  of  timer  A,  as  the  clock 
signal  from  timer  A  is  reflected  in  the  CNT  line.  (CNT  changes  value  on 
each  timeout;  on  every  falling  edge,  that  is,  high  to  low  transition  on  the 
CNT  line,  the  next  bit  appears  on  the  SP  line.) 

The  transfer  begins  with  the  MSB  of  the  data  byte.  Once  all  eight  bits 
have  been  output,  CNT  remains  high  and  the  SP  line  retains  the  value  of 
the  last  bit  sent.  In  addition,  the  SP  bit  in  the  interrupt  control  register  is 
set  to  show  that  the  shift  register  can  be  supplied  with  new  data.  If  the 
next  data  byte  was  loaded  into  the  data  register  before  the  output  of  the 
last  bit,  the  data  output  continues  without  interruption. 

To  keep  the  transfer  continuous,  the  serial  data  register  must  be  supplied 
with  new  data  at  the  proper  time.  The  SP  and  CNT  lines  are  open- 
collector  outputs  so  that  CNT  and  SP  lines  of  multiple  8520s  can  be 
connected  together. 

The  Interrupt  Control  Register  (ICR): 

Read  access  =  data  register 
Register       Name       D7       D5      D5       D4  D3 D2 DT DO" 


13  $D       I  ICR      |  IR     |  0     |  0       |  FLAG     |  SP    |  Alarm    |   IB    |  TA' 


Write  access  =  mask  register 
Register       Name      t>7       D6      D5       D?~         D3       D2  D1 DC 


Register       Name       u/       D6      us       D4  D5       D2  DT DO-! 

13  $U       I  ICR      |  S/C  I  x      |  x       |  FLAG      |  SP    I  Alarm     |    IB    |  TA~ I 


The  ICR  consists  of  a  data  register  and  a  mask  register.  Each  of  the  five 
interrupt  sources  can  set  its  corresponding  bit  in  the  data  register.  Here 
again  are  all  five  possible  interrupt  sources: 

1.  Timeout  of  timer  A  (TA,  bit  0). 

2.  Timeout  of  timer  B  (TB,  bit  1). 
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3.  Match  of  event  counter  value  and  alarm  value  (Alarm,  bit  2). 

4.  The  shift  register  of  the  serial  port  is  full  (input)  or  empty  (output) 
(SP,bit3). 

5.  Negative  transition  on  the  FLAG  input  (FLAG,  bit  4). 

If  the  ICR  register  is  read,  what  is  returned  is  always  the  value  of  the  data 
register,  which  is  subsequently  cleared  (all  set  bits,  including  the  IR  bit 
are  cleared).  If  the  value  of  the  data  register  is  still  needed,  it  must  be 
stored  in  RAM  after  the  read. 

The  mask  register  can  only  be  written.  Its  value  determines  whether  a  set 
bit  in  the  data  register  can  generate  an  interrupt.  To  make  an  interrupt 
possible,  the  corresponding  bit  in  the  mask  register  must  be  set  to  1.  The 
8520  pulls  the  IRQ  line  low  (it  is  active  low)  whenever  a  bit  is  set  in  both 
the  data  register  and  the  mask  register  and  sets  the  IR  bit  (bit  7)  in  the 
data  register  so  that  an  interrupt  is  also  signaled  in  software.  The  IRQ  line 
does  not  return  to  1  until  the  ICR  is  read  and  thus  cleared. 

The  mask  register  cannot  be  written  like  an  ordinary  memory  location.  To 
set  a  bit  in  the  mask  register,  the  desired  bit  must  be  set  and  the  S/C  bit 
(Set/Clear,  bit  7)  must  also  be  set.  All  other  bits  remain  unchanged.  To 
clear  a  bit,  the  desired  bit  must  again  be  set,  but  this  time  the  S/C  bit  is 
cleared.  The  S/C  bit  determines  whether  the  set  bits  will  set  (S/C=l)  or 
clear  (S/C=0)  the  corresponding  bits  in  the  mask  register.  All  cleared  bits 
in  the  byte  written  to  the  mask  register  have  no  effect  on  it. 

Here  is  an  example:  We  want  to  allow  an  interrupt  through  the  FLAG 
line.  The  current  value  of  the  mask  register  is  0000001 1  binary,  meaning 
that  both  timer  interrupts  are  allowed. 

The  following  value  must  be  written  into  the  mask  register:  10010000 
binary  (S/C  =1).  The  mask  register  then  has  the  following  contents: 
00010011. 

If  you  now  want  to  turn  the  two  timer  interrupts  off,  write  the  following 
value:  00000011  (S/C=0).  Now  the  mask  register  contains  00010000, 
and  only  the  FLAG  interrupt  is  allowed. 
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Integration  of  the  CIAs  into  the  Amiga  system 

As  previously  mentioned,  the  Amiga  has  two  CIAs  of  the  type  8520.  The 
base  address  of  the  first  8520,  which  we  call  8520-A,  is  $BFE001.  The 
registers  are  not  at  contiguous  memory  addresses,  however.  Instead  they 
are  at  256  byte  intervals. 

This  means  that  all  of  the  8520-A  registers  are  at  odd  addresses  because 
the  8520-A  is  connected  to  the  lower  8  lines  of  the  processor  data  bus 
(DO-7).  Between  the  68030  and  the  CIAs  is  a  bus  adapter.  This  forms  the 
68000-style  synchronous  bus  interface.  Originally  this  transfer  protocol 
from  the  8-bit  (6800)  era  was  implemented  in  the  68000  for  compatibility 
with  the  peripheral  ICs  that  existed  at  that  time.  As  the  dramatic  success 
of  the  68000  became  apparent,  special  ICs  for  its  asynchronous  bus  were 
made  available,  and  the  synchronous  bus  was  dropped  from  the  later 
processors  (68020,  30  and  40).  The  special  logic  of  the  bus  adapter 
allows  the  CIAs  from  older  Amigas,  which  were  also  retained  for 
compatibility,  to  be  connected  to  the  68030  bus. 

The  following  table  lists  the  addresses  of  the  individual  registers  with 
their  uses  in  the  Amiga  (refer  to  the  section  on  interfaces  for  more 
information  on  the  individual  port  bits): 

CI  A- A:  Register  addresses 


Address 

Name 

u/          U6           D5           D4          D3            D2 

D1 

DO 

$BFE001 

PRA 

/FIR1       /FIHO        /RDY       /TKO       /WPHO     /CHNG 

/LED 

OVL 

$BFE101 

PRB 

Centronics  parallel  port 

$BFE201 

DDRA 

0             0              0              0             0                0 

1 

1 

$BFE301 

DDRB 

Input  or  output  depending  on  the  application 

$BFE401 

TALO 

Timer  A  is  used  by  the  operating  system  for  communication 

$BFE501 

TAHI 

with  the  keyboard 

$BFE601 

TBLO 

Timer  B  is  used  by  the  OS  for  various  tasks 

$BFE701 

TBHI 

$BFE801 

E.  LSB 

The  event  counter  in  CIA-A  counts  50  Hz 

$BFE901 
$BFEA01 

E.8-15 

pulses  from  the  power  supply  (called  ticks),  which 
are  taken  from  the  power-line  frequency 

E.  MSB 

$BFEC01 

SP 

Input  for  key  codes  from  the  keyboard 

$BFED01 

ICR 

Interrupt  control  register 

$BFEE01 

CRA 

Control  register  A 

$BFEF01 

CRB 

Control  register  B 

The  second  CIA,  CIA-B,  is  referenced  at  address  $BFD000.  Its  registers 
lie  at  even  addresses  because  the  data  bus  of  CIA-B  is  connected  to  the 
upper  half  of  the  processor  data  bus. 
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C1A-B:  Register  addresses 


Address 

Name 

D/          D6            D5           D4          D3 

D2 

D1 

DO 

$BFDOOO 

PRA 

/DTR      /RTS        /CD         yCTS      /DSR 

SEL 

POUI 

BUSY 

$BFD100 

PRB 

/MTR       /SEL3        /SEL2       /SEL1      /SELO 

/SIDE 

DIR 

/STEP 

$BFD200 

DDRA 

110               0             0 

0 

0 

0 

$BFD300 

DDRB 

11111 

1 

1 

1 

$BFD400 

TALO 

Timer  A  is  used  only  for  serial  data  transfer 

$BFD500 

TAHI 

otherwise  it  is  free 

$BFD600 

TBLO 

Timer  B  is  used  to  synchronize  the  blitter  with  the 

screen 

$BFD700 

TBHI 

otherwise  it  is  free 

$BFD800 

E.  LSB 

The  event  counter  in  CIA-B  counts  the 

$BFD900 

E.8-15 

horizontal  sync  pulses 

$BFDA00 

E.  MSB 

1 5625  per  second  (PAL  standard) 

$BFDC00 

SP 

Unused 

$BFDD00 

ICR 

Interrupt  control  register 

$BFDEOO 

CRA 

Control  register  A 

$BFDF00 

CRB 

Control  register  B 

The  following  list  shows  the  various  signal  lines  of  the  Amiga's  CIAs: 
C1A-A 


/IRQ 

/INT2  input  from  Paula 

/RES 

System  reset  line 

D0-D7 

Processor  data  bus  bits  0-7 

A0-A3 

Processor  address  bus  bits  8-1 1 

Phi2 

CIA  clock  input  (71 6  kHz) 

R/W 

Processor  R/W 

PA7 

Game  port  1  pin  6  (fire  button) 

PA6 

Game  port  0  pin  6  (fire  button) 

PA5 

/RDY            "disk  ready"  signal  from  disk  drive 

PA4 

/TKO             "disk  track  00"  signal  from  disk  drive 

PA3 

/WPRO        "write  protect"  signal  from  disk  drive 

PA2 

/CHNG        "disk  change"  signal  from  disk  drive 

PA1 

LED             Control  over  the  power  LED  (0  =  on,  1  =  off) 

PAO 

OVL             Memory  overlay  bit  (do  not  change!) 

SP 

KDAT           Serial  keyboard  data                                              j 

CNT 

KCLK           Clock  for  keyboard  data 

PB0-PB7 

Centronics  port  data  lines 

PC 

/DRDY         Centronics  handshake  signal:  data  ready 

FLAG 

/ACK            Centronics  handshake  signal:  data  acknowledge 
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CIA-B 


/IRQ 

/INT6  input  from  Paula 

/RES 

System  reset  line 

D0-D7 

Processor  data  bus  bits  8-15 

A0-A3 

Processor  address  bus  bits  8-1 1 

Phi2 

CIA  clock  input  (716  kHz) 

R/W 

Processor  R/W 

PA7 

/DTR                          Serial  interface,  /DTR  signal 

PA6 

/RTS                         Serial  interface,  /RTS  signal 

PA5 

/CD                           Serial  interface,  /CD  signal 

PA4 

/CTS                         Serial  interface,  /CTS  signal 

PA3 

/DSR                         Serial  interface,  /DSR  signal 

PA2 

SEL                          "select"  signal  for  Centronics  interface 

PA1 

POUT                       "paper  out"  signal  from  Centronics  interface 

PAO 

BUSY                       "busy"  signal  from  Centronics  interface 

SP 

BUSY                       connected  directly  to  PAO 

CNT 

POUT                        connected  directly  to  PA1 

PB7 

/MTR                          "motor"  signal  to  disk  drive 

PB6 

/SEL3                        "drive  select"  for  drive  3 

PB5 

/SEL2                        "drive  select"  for  drive  2 

PB4 

/SEL1                          "drive  select"  for  drive  1 

PB3 

/SELO                        "drive  select"  for  drive  0  (internal) 

PB2 

/SIDE                        "side  select"  signal  to  disk  drive 

PB1 

D I R                           "direction"  signal  to  disk  drive 

PBO 

/STEP                       "step"  signal  to  disk  drive 

FLAG 

/INDEX                      "index"  signal  from  disk  drive 

PC 

Not  used 
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11.4   Custom  Chips  and  the  Amiga 

The  key  component  of  every  Amiga  system,  besides  the  processor,  is  the 
unit  formed  by  Commodore's  own  specially  developed  custom  chips, 
Agnus,  Denise  and  Paula.  In  the  course  of  the  Amiga's  development, 
Agnus  and  Denise  have  undergone  several  revisions.  The  versions  used 
•  ;  in  the  Amiga  3000  are  called  8372B,  8373  and  8364.  These  custom  chips 
handle  sound  generation,  screen  display,  processor-independent  diskette 
access  and  much  more.  These  tasks  are  not  strictly  divided  up  among  the 
chips  so  that  one  is  in  charge  of  sound  generation,  one  of  graphics  and 
another  of  diskette  operation,  which  is  usually  the  case  with  such 
devices.  Instead  most  tasks  are  shared  among  the  chips,  so  that  graphics 
display,  for  example,  is  accomplished  by  two  chips  working  together. 

Although  the  three  chips  could  have  been  combined  into  one,  it  would 
be  more  expensive  to  produce  such  a  complex  circuit  than  the  three 
separate  chips. 

Other  special  components  are  also  needed  to  control  a  system  as  complex 
as  the  Amiga  3000.  These  include  a  revised  Buster  chip  for  controlling 
the  expansion  slots,  a  revised  Gary  as  system  controller,  a  newly 
developed  32-bit  DMA  controller  for  the  SCSI  interface  (needed  by  the 
hard  disk),  a  Western  Digital  SCSI  interface  chip,  a  controller  chip  for  the 
FastRAM  and  a  component  named  Amber  as  core  of  the  built-in  flicker 
fixer.  Before  we  explain  how  Agnus,  Denise,  Paula,  and  the  other  special 
components  work,  first  we'll  discuss  the  structure  of  the  Amiga  3000. 
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11.4.1         Basic  Structure  of  the  Amiga 


o  and  from  hterf&CM 


0       0 


The  structure  of  the  68030 

A  simple  computer  system  normally  consists  of  a  processor,  the  ROM 
with  the  operating  system,  a  certain  amount  of  RAM,  and  at  least  one 
peripheral  component  for  data  input  and  output.  All  components  are 
connected  to  the  address  and  data  bus.  The  processor  controls  the 
system  and  only  it  can  place  addresses  on  the  bus  and  thus  read  or  write 
data  to  and  from  various  system  components,  such  as  RAM.  It  also 
controls  bus  control  signals  like  the  R/W  line.  Every  system  also  contains 
control  circuits  like  an  address  decoder,  which  activates  certain 
components  based  on  values  on  the  address  bus. 

Now  let's  discuss  the  Amiga.  As  you  can  see  from  the  above  diagram,  the 
structure  of  the  Amiga  deviates  somewhat  from  what  we  described.  On 
the  left  side  you  see  the  68030  microprocessor,  whose  data  and  address 
lines  are  connected  directly  to  the  two  8520  CIAs,  the  Kickstart  ROM, 
the  real-time  clock  and  the  DMA  controller.  The  Gary  chip  manages  the 
control  lines  so  that  the  68030  can  access  all  these  different  components. 
It  informs  the  68030,  for  example,  whether  it  must  perform  a  16-  or  a  32- 
bit  access  to  a  particular  address. 

A  new  chip  called  Ramsey  takes  over  the  management  of  RAM 
(configured  with  full  32-bit  addresses,  of  course),  with  the  capability  of 
handling  up  to  16  Megabytes  of  fast  RAM.  This  RAM  can  be  accessed 


722 


11.4  Custom  Chips  and  the  Amiga 


by  the  DMA  controller  or  DMA-capable  expansion  cards  as  well  as  by 
the  processor. 

The  four  expansion  slots  are  connected  to  the  processor  address  and 
data  lines  with  a  set  of  drivers.  These  drivers  are  controlled  by  the 
A3000's  Fat  Buster  chip,  an  enhanced  version  of  the  A2000's  Buster. 
This  chip  also  controls  bus  allocation  on  DMA  access.  When  the  SCSI 
controller  or  an  expansion  card  wants  to  access  RAM  directly,  first  it 
must  get  permission  to  use  the  processor's  bus  lines.  Buster  manages 
these  requests  and  communicates  with  the  CPU,  granting  the  appropriate 
DMA  controller  permission  to  use  the  bus  as  soon  as  the  CPU  frees  it. 

On  the  right  side  of  the  diagram  we  find  the  three  custom  chips  Agnus, 
Denise  and  Paula,  and  the  chip  RAM,  which  are  all  connected  to  a 
common  data  bus.  However,  this  data  bus  is  separated  from  the  processor 
data  bus  by  a  buffer,  which  can  either  connect  the  processor  data  bus  to 
the  chip  data  bus  or  can  separate  the  two.  The  three  custom  chips  are 
connected  to  each  other  through  the  address  register  bus,  which  is 
directed  by  Agnus.  Since  the  chip  RAM  has  a  much  larger  address  range 
than  the  custom  chips  and  also  requires  multiplexed  addresses,  there  is  a 
separate  chip  RAM  address  bus.  Multiplexed  addresses  implies  that  the 
RAM  chips  used  in  the  Amiga  have  an  address  range  of  2*8  addresses 
(256K)  and  in  order  to  access  all  the  addresses  of  a  chip,  18  address  lines 
are  needed.  But  the  actual  chips  are  very  small,  and  such  a  large  number 
of  address  lines  would  require  a  very  large  enclosure.  To  get  around  this 
problem,  something  called  multiplexed  addressing  was  introduced.  The 
package  has  only  nine  address  lines;  first  the  upper  nine  bits  of  the 
address  and  then  the  lower  nine  are  applied  to  these  lines.  The  chip 
stores  the  upper  nine  and  then,  when  the  lower  nine  are  applied  to  the 
address  lines,  it  has  the  18  address  bits  that  it  needs. 

Why  are  these  two  buses  separated?  The  reason  is  that  the  various 
input/output  devices  need  a  constant  supply  of  data.  For  example,  the 
data  for  individual  dots  on  the  screen  must  be  read  from  the  RAM  fifty 
times  per  second,  since  a  television  picture  according  to  the  PAL 
standard  is  refreshed  at  the  rate  of  fifty  times  per  second. 

A  high-resolution  graphic  on  the  Amiga  can  require  more  than  64K  of 
screen  memory.  This  means  that  per  second  50  x  64K  access  must  be 
applied  to  memory.  This  is  nearly  2  million  memory  accesses  per  second. 
If  the  processor  had  to  perform  this  task,  it  would  be  hopelessly 
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overloaded.  Such  a  high  data  rate  would  leave  even  the  68030  little  time 
for  anything  else.  Furthermore,  the  Amiga  can  perform  digital  sound 
output  and  diskette  accesses  in  addition  to  the  graphics,  all  without 
using  the  CPU.  The  solution  lies  in  the  use  of  another  processor  that 
performs  all  these  memory  accesses  itself.  Such  a  processor  is  also  called  a 
DMA  (Direct  Memory  Access)  controller,  and  the  A3000  has  two  of 
them,  the  SCSI-DMA  chip  and  Agnus. 

While  the  SCSI  chip  is  needed  only  to  speed  up  data  transfer  between 
RAM  and  the  SCSI  interface,  Agnus  has  more  numerous  and  varied 
capabilities.  However,  Agnus  can  access  only  the  chip  RAM.  Agnus 
contains  not  only  the  DMA  controller,  but  also  the  RAM  controller  for 
the  chip  RAM.  This  is  why  Agnus  is  also  connected  to  the  chip  RAM 
address  bus.  The  processor  can  access  chip  RAM  only  by  using  Agnus. 

The  other  chips,  Denise  and  Paula,  and  also  the  remainder  of  Agnus,  are 
constructed  like  standard  peripheral  chips.  They  have  a  certain  number 
of  registers  which  can  be  read  or  written  by  the  processor  (or  the  DMA 
controller).  The  individual  registers  are  selected  through  the  register 
address  bus.  It  has  eight  lines,  so  256  different  states  are  possible.  There 
is  no  special  chip  selection.  If  the  address  bus  has  the  value  255  or  $FF, 
so  that  all  lines  are  high,  no  register  is  selected.  If  a  valid  register  number 
is  on  these  lines,  then  the  chip  containing  the  selected  register  recognizes 
this  and  activates  it.  This  task  is  performed  in  the  individual  chips  by  the 
register  address  decoders.  The  fact  that  the  selection  of  a  register 
depends  only  on  its  register  address  and  not  on  the  chip  in  which  it  is 
located  means  that  two  registers  in  two  different  chips  can  be  written 
with  the  same  value  if  they  have  the  same  register  address.  This 
capability  is  used  for  some  of  the  registers  that  contain  data  needed  by 
more  than  one  chip. 

Each  chip  register  can  be  either  a  read  register  or  a  write  register. 
Switching  between  read  and  write  by  means  of  a  special  R/W  line,  like  in 
the  8520,  is  not  possible.  The  register  address  alone  determines  whether  a 
read  or  write  address  is  taking  place.  Registers  that  can  be  both  read  and 
written  are  realized  by  having  write  access  go  to  one  register  address  and 
read  access  to  another.  This  property  is  more  clearly  shown  in  the  list  of 
chip  registers. 

Since  Agnus  contains  the  DMA  controller,  it  can  also  access  the  custom 
chip  registers  itself  by  outputting  an  address  on  the  register  address  bus. 
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One  obvious  problem  is  still  unresolved.  There  is  only  one  data  bus  and 
one  address  bus,  which  both  the  processor  and  the  DMA  controller  want 
to  access.  A  bus  can  be  controlled  by  only  one  bus  controller  at  a  time.  If 
two  chips  tried  to  place  an  address  on  the  bus  simultaneously,  there 
would  be  a  problem  known  as  bus  contention,  leading  to  a  system  crash. 
Therefore  the  chips  must  share  access  to  the  bus  by  taking  turns. 
Naturally  each  would  like  to  have  the  bus  for  itself  as  often  as  possible. 
This  problem  is  solved  by  the  Amiga  on  three  levels: 

First,  both  normally  continuous  buses  are  divided  on  the  Amiga  into  two 
parts.  One  (on  the  left  in  the  diagram)  connects  all  the  components  that 
are  usually  accessed  only  by  the  processor.  (Although  the  SCSI 
controller  and  expansion  cards  can  also  access  RAM  on  the  processor's 
behalf,  these  DMA  accesses  usually  take  place  only  when  needed,  for 
example,  when  accessing  a  SCSI  hard  disk,  which  reduces  processor 
speed.)  When  the  68030  accesses  one  of  these  components,  Gary  uses 
the  buffers  to  break  the  connections  of  the  processor  address  and  data 
buses  to  the  chip  address  and  data  buses.  This  way  both  the  processor 
and  Agnus,  each  on  its  own  side,  can  access  the  bus  undisturbed.  This 
gives  the  processor  quick  access  to  the  operating  system  and  to  its  RAM. 
This  RAM  connected  directly  to  the  processor  data  and  address  bus  is 
called  fast  RAM,  since  the  processor  can  always  access  it  without 
slowing  down,  if  it  has  the  bus  at  that  moment. 

Secondly,  bus  accesses  from  Agnus  and  from  the  processor  are  nested,  so 
that  normally  even  on  accesses  to  chip  RAM  or  chip  registers,  a  68000 
does  not  have  to  be  delayed.  For  such  an  access  the  buffers  connect  the 
two  systems  again. 

As  a  third  and  final  solution,  the  processor  can  wait  until  Agnus  has 
finished  its  DMA  accesses  and  the  bus  is  free  again.  This  occurs  only 
when  very  high  graphics  resolutions  have  been  selected  or  the  Blitter  is 
being  used.  Agnus,  Denise  and  Paula  were  originally  drafted  for  an 
Amiga  with  a  68000  processor.  Despite  certain  revisions  for  the  A3000, 
they  have  some  problems  working  with  the  68030.  Nesting  the  accesses 
to  chip  RAM  on  an  Amiga  with  the  68000  enables  alternating  access;  so 
the  processor  does  not  have  to  wait.  The  A3000's  68030,  however, 
accesses  memory  with  substantially  higher  speed,  while  Agnus's  clock 
frequency  remains  unchanged.  The  result  is  that  the  A3000's  CPU  must 
insert  wait  cycles  when  it  wants  to  access  chip  RAM. 
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Another  disadvantage  of  the  custom  chips  is  their  limitation  to  a  16-bit 
wide  data  bus.  While  the  A3000  manages  chip  RAM  as  true  32-bit  RAM, 
special  buffers  are  required  for  RAM  access  by  Agnus  to  ensure  that 
access  proceeds  to  the  correct  half  of  the  chip  RAM  data  bus. 

11.4.2        The  Structure  of  Agnus 

The  2  Meg  version  of  Agnus  in  the  A3000  is  also  called  Super  Agnus. 

All  clock  generation  for  the  custom  chips  is  integrated  in  Fat  Agnus. 
Only  the  28  MHz  base  clock  must  be  supplied.  Agnus  also  assumes  the 
management  of  chip  RAM,  generating  the  necessary  RAS  and  CAS 
signals  together  with  the  multiplexed  RAM  addresses.  Agnus  can 
manage  chip  RAM  on  its  own.  But  since  the  A3000's  developers  wanted 
to  endow  it  with  true  32-bit  chip  RAM  access,  a  conversion  process  was 
necessary  to  utilize  the  16-bit  wide  data  bus.  Since  Agnus  is  still  used  in 
the  older  Amiga  models,  other  chips  were  connected  to  Agnus  for  this 
purpose,  instead  of  being  integrated  into  it. 

Agnus's  main  responsibility  is  all  of  the  DMA  control.  Each  of  the  six 
possible  DMA  sources  has  its  own  control  logic.  They  are  all  connected 
to  the  chip  RAM  address  generator  as  well  as  the  register  address 
generator.  These  address  generators  create  the  RAM  address  of  the 
desired  chip  RAM  location  and  the  register  address  of  the  destination 
register.  In  this  manner  the  DMA  logic  units  supply  the  appropriate  chip 
registers  with  data  from  the  RAM  or  write  the  contents  of  a  given 
register  into  RAM. 

Also  connected  to  the  chip  RAM  address  generator  is  the  refresh 
counter,  which  creates  the  refresh  signals  necessary  for  the  operation  of 
the  dynamic  RAM  chips. 

Agnus  controls  the  synchronization  of  the  individual  DMA  accesses.  The 
fundamental  reference  for  this  is  a  screen  line.  In  each  screen  line,  255 
memory  accesses  take  place,  which  Agnus  allocates  among  the  individual 
DMA  channels  and  the  68030.  Since  it  always  needs  the  current  row 
and  column  positions  for  this,  Agnus  also  contains  the  raster  and  column 
counters.  These  counters  for  the  beam  position  also  create  the  horizontal 
and  vertical  synchronization  signals,  which  signal  to  the  monitor  the  start 
of  a  new  line  (H-sync)  and  a  new  picture  (V-sync).  The  horizontal  and 
vertical  synchronization  signals  can  also  be  fed  in  from  outside  Agnus 
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and  then  control  the  internal  raster  line  and  column  counters.  This  allows 
the  video  picture  of  the  Amiga  to  be  synchronized  to  that  of  another 
source,  such  as  a  video  recorder.  Called  a  genlock,  this  is  easily 
accomplished  on  the  Amiga.  (Simply  stated,  synchronizing  two  video 
pictures  means  that  the  individual  raster  lines  and  the  individual  pictures 
of  the  two  signals  start  at  the  same  time.) 

Two  other  important  elements  in  Agnus  are  the  Blitter  and  the  Copper 
coprocessor.  The  Blitter  is  a  special  circuit  that  can  manipulate  or  move 
areas  of  memory.  It  can  be  used  to  relieve  the  68030  of  some  work,  since 
it  can  perform  these  operations  faster  than  the  processor  can.  In  addition, 
the  Blitter  is  capable  of  drawing  lines  and  filling  surfaces.  The  Copper  is  a 
simple  coprocessor.  Its  programs,  called  Copper  lists,  contain  only  three 
different  commands.  The  Copper  can  change  various  chip  registers  at 
predetermined  points  in  time. 

The  following  are  the  functions  of  the  individual  pins: 

Data  bus:  D0-D15 

The  16  data  lines  are  connected  directly  to  the  chip  RAM  data  bus. 
Internally  all  of  the  chip  registers  are  connected  through  a  buffer  to  the 
bus. 

Processor  address  bus:  A1-A20 

These  inputs  are  connected  with  the  address  lines  of  the  68030  and  are 
used  by  Agnus  when  the  CPU  accesses  chip  RAM  or  one  of  the  chip 
registers. 

CPU  bus  signals:  _LDS,_UDS,_R/W  and  _AS 

These  signals  inform  Agnus  about,  among  other  things,  the  validity  of 
processor  addresses. 

Register  address  bus:  RGA1-RGA8  (ReGister Address) 

On  a  DMA  access  Agnus  selects  the  appropriate  chip  register  over  the 
register  address  bus.  If  the  _REGEN  line  is  low,  meaning  the  processor  is 
accessing  a  chip  register,  Agnus  transfers  the  CPU-referenced  register 
address  to  the  register  address  bus.  With  a  value  of  $FF  on  the  register 
address  bus  (all  lines  high),  this  is  inactive. 
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The  address  lines  for  the  dynamic  RAM:  DRA0-DRA9  (Dynamic  RAM 
Address) 

Agnus  always  generates  the  multiplexed  addresses  for  the  chip  RAM.  On 
a  DMA  access  these  originate  from  one  of  the  internal  address  counters, 
the  processor  signals  access  to  RAM  (_RAMEN  low),  and  Agnus  simply 
switches  the  addresses  through  to  chip  RAM.  Agnus  can  address  2  Meg 
of  chip  RAM  (2x10  address  lines  for  20  address  bits,  220  gives  an  area 
of  roughly  1  million  addresses,  but  since  the  chip  RAM  for  Agnus  has  a 
width  of  16  bits,  the  memory  available  to  Agnus  is  2  Meg). 

The  chip  RAM  control  lines:  _RAS,_CASU,_CASL,_WE 

The  _RAS  and  _CAS  signals  activate  the  dynamic  RAM  chips.  The  _WE 
line  determines  whether  Agnus  is  writing  data  to  chip  RAM  or  reading 
from  it. 

The  bus  control  signals:  _RAMEN,  _REGEN,  BLITS,  _BUT 

These  four  lines  are  connected  to  Gary.  With  the  _BLIT  line  Agnus  tells 
Gary  that  it  will  take  over  the  bus  on  the  next  bus  cycle.  This  line  always 
takes  precedence  over  a  processor  bus  request.  If  Agnus  requires  the  bus 
for  several  consecutive  bus  cycles,  the  68030  must  wait. 

The  _RAMEN  (RAM  ENable)  and  _REGEN  (REGister  ENable)  inform 
Agnus  that  the  processor  wants  to  access  chip  RAM  or  a  chip  register. 

The  BLITS  signal  (BLITter  Slow  down)  signals  Agnus  that  the  processor 
is  waiting  for  access.  Depending  on  the  internal  status,  Agnus  gives  up 
the  bus  to  the  processor  for  a  cycle. 

The  control  signals:  RES,  1NT3,  DMAL 

The  RES  signal  (RESet)  is  connected  directly  to  the  system  reset  line  and 
returns  Agnus  to  a  predefined  start-up  state. 

The  INT3  line  (INTerrupt  at  level  3)  is  an  output  and  is  connected 
directly  to  the  Paula  line  with  the  same  name.  Agnus  uses  this  line  to 
inform  the  interrupt  logic  in  Paula  that  a  component  in  Agnus  has 
generated  an  interrupt. 
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The  DMAL  line  (DMA  Request  Line)  also  connects  Agnus  to  Paula;  only 
this  time  the  connection  occurs  in  the  opposite  direction.  Paula  uses  this 
line  to  tell  Agnus  to  perform  a  DMA  transfer. 

The  synchronization  signals:  HSY,  VSY,  CSY  and  LP 

Normally  the  synchronization  signals  for  the  monitor  appear  on  the  HSY 
(Horizontal  SYnc)  and  VSY  (Vertical  SYnc)  lines.  The  signal  on  the  CSY 
(Composite  SYnc)  line  is  the  sum  of  HSY  and  VSY  and  is  used  to 
connect  to  monitors  that  need  a  combined  signal,  as  well  as  the  circuit 
that  creates  the  video  signal,  the  video  mixer. 

The  LP  line  (Light  Pen)  is  an  input  line  for  connecting  a  light  pen.  The 
content  of  the  raster  counter  register  is  stored  when  a  negative  transition 
occurs  on  this  pin. 

The  HSY  and  VSY  lines  can  also  be  used  as  inputs  and  thus  allow  Agnus 
to  be  externally  synchronized  (genlock). 

The  clock  lines:  28  MHz,  7  MHz,  CCK,  CCKQ,    CDAC 

The  28  MHz  signal  forms  the  base  clock  for  Agnus.  The  two  7-MHz 
signals,  7  MHz  and  _CDAC,  and  the  two  3.5-MHz  signals,  CCK  and 
CCKQ,  are  produced  from  it.  These  four  serve  as  clock  signals  for  Denise, 
Paula  and  a  few  other  chips. 
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11.4.3        The  Structure  of  Denise 
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Note:    The  arrows  show  the  direction  of  the  signal. 
A  line  above  a  signal  means  the  signal  is 
active  when  low  (0=active). 
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Denise 

In  general,  the  function  of  Denise  can  be  described  as  graph  generation. 
The  first  part  of  this  task  is  already  accomplished  by  Agnus.  Agnus 
fetches  the  current  graphic  data  from  the  chip  RAM  and  writes  them  to 
the  registers  responsible  for  the  bit  level  manipulations  in  Denise.  It  does 
the  same  for  the  sprite  data.  Denise  always  contains  all  graphic  and  sprite 
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data  for  16  pixels,  since  a  bit  always  corresponds  to  one  pixel  on  the 
screen  and  the  data  registers  all  have  a  width  of  one  word,  or  16  bits. 
These  data  must  be  converted  into  the  appropriate  RGB  representation 
by  Denise.  First,  the  graphic  data  are  converted  from  a  parallel  16-bit 
representation  to  a  serial  data  stream  by  means  of  the  bit-level  sequencer. 
Since  a  maximum  of  six  bit  levels  are  possible,  this  function  block  is 
repeated  six  times.  The  serial  data  streams  from  the  individual  bit-level 
sequencers  are  now  combined  into  a  maximum  6-bit  wide  data  stream. 
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Block  circuit  diagram  of  Denise 

The  priority  control  logic  selects  the  valid  data  for  the  current  pixel  based 
on  its  priority  from  among  the  graphic  data  from  the  bit-level  sequencers 
and  the  sprite  data  from  the  sprite  sequencers.  According  to  this  data  the 
color  decoder  selects  one  of  the  32  color  registers.  The  value  of  this 
register  is  then  output  as  a  digital  RGB  signal.  If  the  Hold-And-Modify 
(HAM)  or  the  Extra-Half-Bright  (EHB)  mode  is  selected,  the  data  from 
the  color  register  is  modified  accordingly  before  it  leaves  the  chip. 

The  data  from  the  sequencers  is  also  fed  into  the  collision-control  logic. 
As  its  name  implies,  this  checks  the  data  for  a  collision  between  the  bit 
levels  and  the  sprites  and  places  the  results  of  this  test  into  the  collision 
register. 
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The  last  function  of  Denise  has  nothing  to  do  with  the  screen  display. 
Denise  also  contains  the  mouse  counter,  which  contains  the  current  X 
and  Y  positions  of  the  mice. 

Here  is  a  functional  description  of  Denise's  pins: 

The  data  bus:  D0-D15 

The  16  data  bus  lines  are,  like  those  of  Agnus,  connected  to  the  chip  data 
bus. 

Register  address  bus:  RGA1-RGA8 

The  register  address  bus  is  a  pure  input  on  Denise.  The  register  address 
decoder  selects  the  appropriate  internal  register  with  the  help  of  the 
value  on  the  register  address  bus. 

The  clock  inputs:  CCK  and  7M 

Denise's  timing  is  regulated  by  the  CCK  signal.  The  CCK  pin  is 
connected  to  the  CCK  pin  on  Agnus.  The  clock  signal  on  the  7M  line  (7 
Megahertz)  has  a  frequency  of  7.15909  MHz.  The  Denise  chip  needs  this 
additional  frequency  to  output  the  individual  pixels  because  the  pixel 
frequency  is  greater  than  the  3.58  MHz  of  the  CCK  signal.  A  pixel  at  the 
lowest  resolution  (320  pixels/line)  has  exactly  the  duration  of  a  7M  clock 
signal.  In  high-resolution  mode  (640  pixels/line)  two  pixels  are  output 
per  7M  cycle,  one  on  each  edge  of  its  signal.  The  output  signals:  R0-3, 
GO-3,  B0-3,  ZD  and  BURST. 

The  lines  R0-3,  GO-3  and  B0-3  represent  the  RGB  outputs  of  Denise. 
Denise  outputs  the  corresponding  values  digitally.  Each  of  the  three 
color  components  is  represented  by  four  bits.  This  allows  16  values  per 
component  and  16x16x16  (4096)  total  colors.  After  they  leave  Denise, 
the  three  color  signals  run  through  a  buffer  and  then  through  three 
digital-to-analog  converters  to  transform  them  into  an  analog  RGB 
signal,  which  is  then  fed  to  the  RGB  port. 

The  last  output  signal  of  Denise  is  the  ZD  signal  (Zero  Detect  or 
background  indicator).  It  is  always  low  when  a  pixel  is  being  displayed 
in  the  background  color  (i.e.,  when  its  color  comes  from  color  register 
number  0).  This  signal  is  used  in  the  genlock  adapter  for  switching 
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between  the  external  video  signal  (ZD=0)  and  the  Amiga's  video  signal 
(ZD=1).  The  ZD  signal  is  also  available  on  the  RGB  port. 

The  mouse/ joystick  inputs:  MOH,  M1H,  MOV,  M1V 

These  four  inputs  correspond  directly  to  the  mouse  inputs  of  the  two 
game  ports  (or  joystick  connectors).  Since  the  Amiga  has  two  game  ports, 
it  must  actually  have  eight  inputs.  Apparendy  only  four  pins  were  free  on 
Denise  so  Commodore  used  the  following  method  to  read  all  the  inputs: 
The  eight  input  lines  of  the  two  game  ports  go  to  a  switch,  which 
connects  the  four  lines  of  either  the  front  or  the  back  port  to  the  four 
inputs  on  Denise.  This  switching  is  performed  in  synchronization  with 
Denise's  clock,  so  that  Denise  can  internally  distribute  the  four  lines  to 
two  registers,  one  for  each  game  port.  The  section  on  interfaces  contains 
more  information  about  the  game  ports. 
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11.4.4        The  Structure  of  Paula 


•4 — ►  P0T1X 
ANAGND 


NOTE: 


The  arrows  show  the  direction  of  the  signal. 

A  line  above  a  signal  means  the  signal  is  active  when  low  (Osactive). 


Paula 

Paula's  tasks  fall  mainly  in  the  I/O  area,  namely  the  diskette  I/O,  the  serial 
I/O,  the  sound  output  and  reading  the  analog  inputs.  In  addition,  Paula 
handles  all  interrupt  control.  All  the  interrupts  that  occur  in  the  system 
run  through  this  chip.  From  the  fourteen  possible  interrupt  sources,  Paula 
creates  the  interrupt  signals  for  the  68030.  Interrupts  on  levels  1-6  are 
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generated  on  the  68030's  IPL  lines.  Paula  gives  the  programmer  the 
possibility  to  allow  or  prohibit  each  of  the  fourteen  interrupt  sources. 

The  disk  data  transfer  and  the  sound  output  are  performed  using  DMA. 
Since,  in  these  two  functions,  Agnus  does  not  know  when  the  next  data 
word  is  ready  for  a  DMA  transfer,  Paula  has  a  DMAL  line,  which  it  can 
use  to  tell  Agnus  when  a  DMA  access  is  needed. 

The  serial  communication  is  handled  by  a  UART  (Universal 
Asynchronous  Receive  Transmit)  component  inside  Paula. 

The  function  of  the  UART,  the  four  audio  channels  and  the  analog  ports 
are  described  later  in  the  section  on  programming  the  custom  chips.  The 
following  is  a  description  of  the  pin  functions: 


DKRD 


DMAL 


TFCTT- 
INT3  - 
jFTTCT- 
1FDT- 
IPL1  ■" 
IPL2  •" 

CCK   - 

CCKQ   - 

RES  - 


RGA1-8 
00-15 


Block  circuit  diagram  of  Paula 
Data  bus:  DO-15 
As  with  the  other  chips,  connected  to  the  chip  data  bus. 
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Register  address  bus:  RGA  1-8 

As  with  Denise. 

The  clock  signals  and  reset:  CCK,  CCKQ  and  RES 

Paula  contains  the  same  clock  signals  as  Agnus.  The  reset  line  RES 
returns  the  chip  to  a  defined  start-up  state. 

DMA  request:  DMAL 

With  this  line  Paula  signals  Agnus  that  a  DMA  transfer  is  needed. 

Audio  outputs:  AUDL  andAUDR 

The  outputs  AUDL  and  AUDR  (AUDio  Left  and  AUDio  Right)  are 
analog  outputs  on  which  Paula  places  the  sound  signals  it  generates. 
AUDL  carries  the  internal  sound  channels  0  and  3,  and  AUDR  the 
channels  1  and  2. 

The  serial  interface  lines:  TXD  andRXD 

RXD  (Receive  Data)  is  the  serial  input  to  the  UART,  and  TXD  (Transmit 
Data)  is  the  serial  output.  These  lines  have  TTL  levels,  which  means  that 
their  input/output  voltages  range  from  0  to  5  volts.  An  additional  level 
converter  subsequently  creates  the  +12/-5  volts  for  the  Amiga's  serial 
RS232  interface. 

The  analog  inputs:  POTOX,  POTOY,  POT1X,  POT1Y 

The  inputs  POTOX  and  POTOY  are  connected  to  the  corresponding  lines 
from  game  port  0,  and  POT1X  and  POT1Y  are  connected  to  port  1. 
Paddles  or  analog  joysticks  can  be  connected  to  these  inputs.  These 
input  devices  contain  variable  resistors,  called  potentiometers,  which  lie 
between  +5  volts  and  the  POT  inputs.  Paula  can  read  the  values  of  these 
resistors  and  place  them  in  internal  registers.  The  POT  inputs  can  also  be 
configured  as  outputs  through  software.  Unfortunately  the  sampling  rate 
is  only  50  Hz  (the  screen  repeat  frequency).  Therefore  it  is  not  possible, 
for  example,  to  use  a  VCR  (Voltage  Controlled  Resistor)  to  digitize  music 
and  speech. 
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The  disk  lines:  DKRD,  DRWD,  DKWE 

Through  the  DKRD  lines  (DisK  ReaD)  Paula  receives  the  read  data  from 
the  diskette.  The  DKWD  line  (DisK  Write)  is  the  output  for  data  to  the 
disk  drive.  The  DKWE  line  (DisK  Write  Enable)  serves  to  switch  the 
drive  from  read  to  write. 

The  interrupt  lines:  1NT2, 1NT3,  INT6  and  1PL0,  IPL1 ,  IPL2 

Paula  receives  instructions  through  the  three  INT  lines  to  create  an 
interrupt  on  the  appropriate  level.  The  INT2  line  is  normally  the  one 
connected  to  the  CIA-A  8520.  This  line  is  also  connected  to  the 
expansion  port  and  the  serial  interface.  If  it  is  low,  Paula  creates  an 
interrupt  on  level  2,  provided  that  an  interrupt  at  this  level  is  allowed. 
The  INT3  line  is  connected  to  the  corresponding  output  from  Agnus  and 
the  INT6  line  to  CIA-B  and  the  expansion  port.  All  other  interrupts  occur 
within  the  I/O  components  in  Paula. 

The  IPL0-IPL2  lines  (Interrupt  Pending  Level)  are  connected  directly  to 
the  corresponding  processor  lines.  Paula  uses  these  to  create  a  processor 
interrupt  at  a  given  level. 
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11.5  The  Amiga  Interfaces 

Every  computer  needs  contact  with  the  outside  world.  Because  of 
various  connections  and  interfaces,  it's  possible  to  connect  the  Amiga  to 
virtually  any  external  device. 


11.5.1        The  Audio  Outputs 


TV  modulator 

1  - 

2  GND 

3  Left  audio  channel 

4  Composite  video  output 

5  GND 

6  - 
7+12V 

8  Right  audio  channel 

Yellow  jack 

Composite  video  signal 

Red  jack 

Left  audio  channel 


White  jack 

Left  audio  channel 


The  audio  outputs 

The  audio  signal  is  available  through  two  phono  connectors  on  the  rear 
of  the  case.  The  right  stereo  channel  is  the  red  connector  and  the  left  is 
the  white.  A  standard  stereo  phono  cable  can  be  used  to  connect  these 
jacks  to  a  stereo  (AUX,  TAPE  or  CD  input).  The  output  resistance  of  each 
channel  is  1  KOhm  (1000  Ohms). 

The  outputs  are  protected  against  short  circuit  and  have  360  Ohms 
impedance. 
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11.5.2        The  RGB  Connector 


/©©©©©@©©©®©©\ 

\©®©©©®©@©©©/ 

INPUT 
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XCLK 

External  clock  frequency 

INPUT 

2 

XCLKEN 

Switch  for  external  clock 

OUTPUT 

3 

R 

Analog  red  signal 

OUTPUT 

4 

G 

Analog  green  signal 

OUTPUT 

5 

B 

Analog  blue  signal 

OUTPUT 

6 

DI 

Digital  brightness  signal 

OUTPUT 

7 

DB 

Pigital  blue  signal 

OUTPUT 

8 

DG 

Digital  green  signal 

OUTPUT 

9 

PR 

Digital  red  signal 

OUTPUT 

10 

OCSY 

Buffered  composite  sync  signal 

IN/OUT 

11 

HSY 

Horizontal  synchronization  signal 

IN/OUT 

12 

VSY 

Vertical  synchronization  signal 

13 

.GND 

OUTPUT 

14 

-ZP 

Background  indicator  signal 

OUTPUT 

15 

C1U 

Amiga  C1U  timer  (3.58  MHz) 

16 

GND 

17 

GND 

18 

GND 

19 

GND 

20 

GND 

21 

-5  volts 

22 

+12  vc 

Its 

23 

+5  volts 

The  RGB  connector 

The  RGB  connector  allows  various  RGB  monitors  as  well  as  special 
expansions,  such  as  a  genlock  adapter,  to  be  connected  to  the  Amiga.  To 
connect  an  analog  RGB  monitor  like  the  standard  Amiga  monitor,  the 
three  analog  RGB  outputs  and  the  CompositeSync  output  are  used.  The 
RGB  signal  on  these  three  lines  comes  from  the  conversion  of  the 
buffered  RGB  digital  signals  from  Denise  into  suitable  analog  signals  by 
means  of  three  4-bit  digital-to-analog  converters.  The  Composite  Sync 
signal  comes  from  Agnus  and  is  formed  by  mixing  the  horizontal  and 
vertical  sync  signals.  All  of  these  four  lines  are  provided  with  transistor 
buffers  and  75  Ohm  series  resistances. 
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The  lines  DI,  DB,  DG  and  DR  are  provided  for  connecting  a  digital  RGB 
monitor.  The  source  of  the  digital  RGB  signals  is  the  digital  RGB  output 
from  Denise.  Each  of  the  three  color  lines  is  connected  to  the  most 
significant  (highest)  respective  color  line  from  Denise  (e.g.,  DB  to  B3 
from  Denise).  Interestingly,  the  intensity  or  brightness  line  DI  is 
connected  to  the  BO  line.  The  four  lines  have  47  Ohm  output  resistances 
and  TTL  levels. 

The  HSY  and  VSY  connections  on  the  RGB  connector  are  provided  for 
monitors  that  require  separate  synchronization  signals.  Use  these  lines 
carefully,  since  they  are  connected  through  47  Ohm  resistors  directly  to 
the  HSY  and  VSY  pins  of  Agnus.  They  also  have  TTL  levels. 

If  the  genlock  bit  in  Agnus  is  set  (see  the  section  on  programming  the 
hardware),  these  two  lines  become  inputs.  The  Amiga  then  synchronizes 
its  own  video  signal  to  the  synchronization  signals  on  the  HSY  and  VSY 
lines.  These  lines  also  require  TTL  levels  as  input.  As  usual,  the 
synchronization  signals  are  active  low,  which  means  that  the  lines  are 
normally  at  5  volts.  Only  during  the  active  synchronization  pulse  is  the 
line  at  0  volts. 

Using  certain  control  bits  from  Agnus,  it  is  also  possible  to  reverse  the 
polarity  of  the  synchronization  signals  (refer  to  Section  1 1.7). 

Kickstart  Versions  1.2  and  later  automatically  recognize  on  reset  whether 
signals  are  present  on  the  two  Sync  lines.  If  so,  the  Amiga  switches  to 
external  synchronization. 

Another  signal,  related  to  genlock,  is  the  ZD  signal  (Zero  Detect).  The 
Amiga  places  this  signal  low  whenever  the  pixel  currently  being 
displayed  comes  from  a  specified  color  register  or  bit-plane. 

During  the  vertical  blanking  gaps,  when  VSY=0,  the  function  of  the  ZD 
line  changes.  Then  it  reflects  the  state  of  the  GAUD  (Genlock  AUDio 
enable)  bit  from  Agnus  register  $100  (BPLCON0).  This  signal  is  used  by 
the  genlock  interface  to  switch  the  sound  signal. 

The  ZD  line  is  usually  of  no  interest  to  the  normal  user,  since  it  is  required 
only  by  the  genlock  interface.  The  ZD  signal  from  Denise  pin  33  is 
buffered  with  a  74HC244  driver,  so  that  the  signal  has  TTL  levels. 
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The  remaining  lines  of  the  RGB  connector  have  nothing  to  do  with  the 
RGB  signal.  The  C1U  line  is  a  3.58  MHz  clock  line  and  corresponds  to 
the  inverted  CLK  signal  of  the  custom  chips. 

The  XCLK  (external  CLocK)  and  XCLKEN  (external  CLocKENable) 
lines  are  used  to  feed  an  external  clock  frequency  into  the  Amiga.  All 
clock  signals  in  the  Amiga  are  derived  from  a  single  28MHz  clock.  This 
28MHz  master  clock  can  be  replaced  by  another  clock  frequency  on  the 
XCLK  input  by  pulling  the  XCLKEN  low.  The  ground  pin  13  should  be 
used  when  using  the  XCLK  and  XCLKEN  lines.  It  is  connected  directly 
with  the  ground  line  of  the  clock  generation  circuit.  The  fed-in  clock 
should  not  differ  greatly  from  the  master  clock  (28  MHz). 


11.5.3        The  VGA  Connector 


©  ©   © 
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1  Red 

2  Green 

3  Blue 

4-8   Ground 
10-12  Ground 

13  H-Sync 

14  V-Sync 


The  VGA  connector 

The  VGA  connector  is  used  for  connecting  IBM- VGA-compatible  or 
multisync  monitors.  It  carries  an  analog  RGB  signal  with  separate  H  and 
V  Sync  lines.  Internally  it  is  connected  to  the  flicker  fixer  output.  A 
switch  on  the  rear  panel  of  the  A3000  can  be  set  so  that  the  flicker  fixer 
passes  the  RGB  signal  unchanged  to  the  VGA  connector. 

Since  the  synchronization  signal  on  the  VGA  connector  is  output  only,  it 
is  not  possible  to  connect  a  genlock  adapter. 
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11.5.4        The  Video  Slot 


The  A3000  video  slot  is  closely  tied  to  the  signals  on  the  RGB  port.  It 
consists  of  two  36-pin  slot  connectors,  identical  to  those  of  the 
expanded  IBM  bus,  which  are  arranged  in  line  with  a  Zorro  expansion 
slot.  The  slots  have  the  following  pin  configurations: 

Rear  slot  (relative  to  rear  of  chassis): 


Pin 

Function 

Pin 

Function 

1 

Reserved 

2 

Reserved 

3 

Left  audio  output 

4 

Right  audio  output 

5 

Reserved 

6 

+5  volts 

7 

Analog  red 

8 

+5  volts 

9 

Ground 

10 

+12  volts 

11 

Analog  green 

12 

Ground 

13 

Ground 

14 

Composite  sync,  direct 

15 

Analog  blue 

16 

/XCLKEN 

17 

Ground 

18 

BURST 

19 

/C4  sync  signal 

20 

Ground 

21 

Ground 

22 

Horizontal  sync 

23 

BO 

24 

Ground 

25 

B3 

26 

Vertical  sync 

27 

G3 

28 

Composite  sync,  buffered 

29 

R3 

30 

/ZD  (also  called  /PIXELSW) 

31 

-5  volts 

32 

Ground 

33 

XCLK 

34 

/C1  sync  signal 

35 

+5  volts 

36 

Pstrobe 
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Front  slot: 


Pin 

Function 

Pin 

Function 

1 

Ground 

2 

RO 

3 

R1 

4 

R2 

5 

Ground 

6 

GO 

7 

G1 

8 

G2 

9 

Ground 

10 

B1 

11 

B2 

12 

Ground 

13 

Composite  video 

14 

TBASE 

15 

CDAC  sync  signal 

16 

POUT  (Paper  out) 

17 

/C3  sync  signal 

18 

BUSY 

19 

/LPEN 

20 

/ACK  (Acknowledge) 

21 

SEL  (Select) 

22 

Ground 

23 

PDO 

24 

PD1 

25 

PD2 

26 

PD3 

27 

PD4 

28 

PD5 

29 

PD6 

30 

PD7 

31 

/LED 

32 

Ground 

33 

Left  audio  unfiltered 

34 

Audio  ground 

35 

Right  audio  unfiltered 

36 

Audio  ground 

Almost  all  these  signals  are  carried  either  by  the  RGB  port  or  the 
Centronics  port.  The  rest  of  the  signals  have  the  following  meanings: 

Left  and  right  audio  outputs: 

These  two  pins  are  connected  directly  to  the  audio  sockets. 

Audio  left/right  unfiltered: 

The  audio  signals  on  these  lines  have  not  yet  gone  through  the  low  pass 
filter. 

7*0  to  R3,  BO  to  B3  and  GO  to  G3: 

These  are  the  digital  RGB  signals  from  Denise,  buffered  through 
74HCT244. 

ILPEN: 

This  is  the  Agnus  lightpen  input. 

/LED: 

This  indicates  the  status  of  the  power  LED  control  line.  It  tells  the 
genlock  card  whether  the  audio  filter  is  on  or  off. 
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Composite  video: 

In  the  A3000,  this  signal  occurs  at  this  slot  only  (unlike  the  older  Amiga 
models,  which  also  had  a  audio  jack  for  it).  It  is  a  video-compatible  black- 
and-white  signal  that  can  be  used,  for  example,  to  connect  the  Amiga  to  a 
TV  with  video  input. 

TBASE: 

TBASE  is  the  time  base  for  the  CIA-A  event  counter,  which  Kickstart 
uses  as  a  system  clock.  A  jumper  can  be  used  to  determine  the  source  of 
TBASE.  This  jumper,  called  J350,  connects  the  TBASE  line  either  with 
the  ticks  from  the  AC  electrical  source  (50  Hz)  or  with  the  VSync  line 
from  Agnus.  Since  its  frequency  is  also  50  Hz,  the  jumper  position  is 
normally  the  same.  Preferably  the  jumper  is  on  the  source  frequency  (pins 
1  and  2),  which  is  generally  more  constant,  causing  the  clock  to  run  more 
accurately. 

11.5.5        The  Centronics  Interface 

The  Centronics  interface  of  the  Amiga  is  a  computer  enthusiast's  dream. 
Any  one  of  a  tremendous  array  of  IBM-compatible  printers  can  be 
connected  directly  to  it. 


Output 

1 

/Strobe  -  data  ready 

I/O 

2 

PDO,  Data  bit  0 

I/O 

3 

PD1,  Data  bit  1 

I/O 

4 

PD2,  Data  bit  2 

I/O 

5 

PD3,  Data  bit  3 

I/O 

6 

PD4,  Data  bit  4 

I/O 

7 

PD5,  Data  bit  5 

I/O 

8 

PD6,  Data  bit  6 

I/O 

9 

PD7,  Data  bit  7 

Input 

10 

/Acknowledge  -  Data  received 

I/O 

11 

BUSY  -  printer  busy 

I/O 

12 

Paper  out 

I/O 

13 

Select  -  printer  ON-LINE 

14 

+5  volts 

15 

Unused 

Output 

16 

Reset/buffered  reset  line  from  Amiga 

17-25 

GND 

Internally  all  of  the  Centronics  port  lines  (except  5  volts  and  Reset)  are 
connected  directly  to  the  port  lines  of  the  individual  CIAs.  The  exact 
assignment  is  as  follows: 


744 


11.5  The  Amiga  Interfaces 


Pin  no. 

Function 

CIA 

Pin 

Designation      j 

1 

Strobe 

A 

18 

PC 

2 

Data  bit  0 

A 

10 

PBO 

3 

Data  bit  1 

A 

11 

PB1 

4 

Data  bit  2 

A 

12 

PB2 

5 

Data  bit  3 

A 

13 

PB3 

6 

Data  bit  4 

A 

14 

PB4 

7 

Data  bit  5 

A 

15 

PB5 

8 

Data  bit  6 

A 

16 

PB6 

9 

Data  bit  7 

A 

17 

PB7 

10 

Acknowledge 

A 

24 

FLAG 

11 

Busy 

B 

2 

PAO 

and 

39 

SP 

12 

Paper  out 

B 

3 

PA1 

and 

40 

CNT 

13 

Select 

B 

4 

PA2 

The  Centronics  interface  is  a  parallel  interface.  The  eight  data  lines  carry 
one  data  byte.  When  the  computer  has  placed  a  valid  data  byte  on  the 
data  lines,  it  clears  the  STROBE  line  to  0  for  1.4  microseconds,  signaling 
the  printer  that  a  valid  byte  is  ready  for  it.  The  printer  must  then 
acknowledge  this  by  pulling  the  Acknowledge  line  low  for  at  least  one 
microsecond.  Once  the  printer  has  indicated  receipt  of  the  data  byte,  the 
computer  can  place  the  next  one  on  the  bus. 

The  printer  uses  the  BUSY  line  to  indicate  that  it  is  occupied  and  cannot 
accept  any  more  data  at  the  moment. 

This  occurs  when  the  printer  buffer  is  full,  for  example.  The  computer 
then  waits  until  BUSY  goes  high  again  before  it  continues  sending  data. 
With  the  Paper  Out  line  the  printer  tells  the  computer  that  it  is  out  of 
paper.  The  Select  line  is  also  controlled  by  the  printer  and  indicates 
whether  it  is  ONLINE  (selected,  SEL  high)  or  OFFLINE  (unselected,  SEL 
low).  The  Centronics  port  is  well  suited  as  a  universal  interface  for 
connecting  home-built  expansions  like  an  audio  digitizer  or  an  EPROM 
burner,  since  almost  all  of  its  lines  can  be  programmed  to  be  either  inputs 
or  outputs. 
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11.5.6        The  Serial  Interface 


Amiga  500/Amiga  2000 


fui  iTsi  nri  [TTirrii  rf?i  [2^  I2T1  f22i  fail  I24I  ^ 


DB-25  male 


Amiga  1000 


jiEDEnaiigEmmsmmmEiiL 

DB-25  female 


The  serial  interface 

The  serial  interface  has  all  of  the  usual  RS-232  signal  lines.  In  addition, 
there  are  many  signals  on  this  connector  that  have  nothing  to  do  with 
serial  communications.  The  lines  TXD,  RXD,  DSR,  CTS,  DTR,  RTS  and 
CD  belong  to  the  RS-232  interface.  The  TXD  and  RXD  lines  are  the 
actual  serial  data  lines. 

The  TXD  line  is  the  serial  output  from  the  Amiga  and  RXD  is  the  input. 
They  are  connected  to  the  corresponding  lines  of  Paula.  The  DTR  line 
tells  the  peripheral  device  that  the  Amiga's  serial  interface  is  in  operation. 

Conversely,  with  the  DSR  line  the  peripheral  device  signals  the  Amiga 
that  its  interface  is  ready  for  operation. 

The  RTS  line  tells  the  peripheral  that  the  Amiga  wants  to  send  serial  data 
over  the  RS-232.  The  peripheral  uses  the  CTS  line  to  tell  the  Amiga  that 
it  is  ready  to  receive  it.  The  CD  signal  is  usually  used  only  with  a  modem 
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and  indicates  that  a  carrier  frequency  is  being  received.  These  five  RS- 
232  control  lines  are  connected  to  CIA-B,  PA3-PA7  as  follows:  DSR- 
PA3;  CTS-PA4;  CD-PA5;  RTS-PA6;  DTR-PA7.  The  RI  line  is  connected 
through  a  transistor  to  the  SEL  line  of  the  Centronics  interface. 


1 

GND 

Frame  Ground 

Output 

2 

TXD 

Transmit  Data 

Input 

3 

RXD 

Receive  Data 

Output 

4 

RTS 

Request  To  Send 

Input 

5 

CTS 

Clear  To  Send 

Input 

6 

DSR 

Data  Set  Ready 

7 

GND 

Signal  Ground 

Input 

8 

CD 

Carrier  Detect 

9 

+12  volts 

10 

-12  volts 

Output 

11 

AUDOUT 

left  sound  channel  output 

12 

Unused 

13 

Unused 

14 

Unused 

15 

Unused 

16 

Unused 

17 

Unused 

Input 

18 

AUDIN 

right  sound  channel  input 

19 

Unused 

Output 

20 

DTR 

Data  Terminal  Ready 

21 

Unused 

Input 

22 

RI 

Ring  Indicator 

23 

Unused 

24 

Unused 

25 

Unused 

Fortunately,  the  RS-232  lines  are  routed  through  RS-232  drivers  instead 
of  being  connected  directly  to  the  chips.  Thus  with  the  appropriate  cable, 
this  interface  can  be  connected  to  almost  all  the  common  terminals  and 
modems.  Type  1488  inverting  RS-232  signal-converters  are  used  as  the 
output  drivers.  They  operate  on  current  supply  in  the  range  of  +12  to  -12 
volts.  This  is  the  range  of  the  output  signals  as  well.  As  input  buffers, 
type  1489 A  chips  are  used.  These  accept  an  input  range  of  -12  to  +0.5 
volts  as  low  and  a  range  of  +3  to  +25  volts  as  high. 

According  to  RS-232  interface  conventions,  the  control  lines  must  be 
active  high,  whereas  the  data  lines  RXD  and  TXD  are  active  low  (logic  1 
is  represented  by  a  low  signal).  Since  the  drivers  invert,  the  CIA-B  port 
bits  that  correspond  to  the  control  lines  are  also  active  low.  This  means 
that  a  bit  with  the  value  0  in  CIA-B  sets  the  corresponding  RS-232 
control  line  to  high.  This  also  applies  to  the  inputs. 
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The  remaining  lines  on  the  RS-232  connector  have  nothing  to  do  with 
RS-232.  The  AUDOUT  line  is  connected  to  the  left  audio  channel  and 
has  its  own  1  KOhm  output  resistance.  The  AUDIN  line  is  connected 
directly  to  the  AUDR  pin  of  Paula  through  a  47  Ohm  resistor.  Audio 
signals  fed  into  the  Amiga  on  the  AUDIN  line  are  sent  along  with  the 
right  sound  channel  from  Paula  over  the  low-pass  filter  to  the  right  audio 
output.  Nothing  else  is  done  to  the  signal. 

The  INT2  line  is  connected  directly  to  the  INT2  input  of  Paula  and  can 
generate  a  level  2  processor  interrupt  if  the  corresponding  mask  bit  is  set 
in  Paula  (see  the  section  on  interrupts).  The  E  line  is  connected  via  a 
buffer  to  the  processor  E  clock  (see  11.2.1).  A  frequency  of  3.58  MHz  is 
available  on  the  MCLK  line,  but  this  is  neither  in  phase  with  the  RGB 
interface  clock  nor  with  the  two  3.58  MHz  clocks  of  the  custom  chips. 
Finally,  the  reset  signal  is  also  available  on  this  connector.  As  you  might 
expect,  it  too  is  buffered. 

11.5.7        The  External  Drive  Connector 


.IIDHimHHHHHUIElUICiL 

[23]   [22]  [21]  [20]  [19]  \n\    [T7]  [7?]  [l?]    [u]  Q5], 

DB-23  female 


The  external  drive  connector 
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Input 

1 

/RDY 

Disk  ready  signal 

Input 

2 

/DKRD 

Read  data  from  disk 

3 

GND 

4 

GND 

5 

GND 

6 

GND 

7 

GND 

Output 

8 

/MTRX 

Motor  on/off 

Output 

9 

/SEL3 

Select  drive  3 

Output 

10 

/DRES 

Disk  reset  (turn  motors  off) 

Input 

11 

/CHNG 

Disk  change 

12 

+5  volts 

Output 

13 

/SIDE 

Side  selection 

Input 

14 

/WPRO 

Write  protect 

Input 

15 

/TKO 

Track  0  indicator 

Output 

16 

/DKWE 

Switch  to  write 

Output 

17 

/DKWD 

Write  data  to  disk 

Output 

18 

/STEP 

Move  read/write  head 

Output 

19 

/DIR 

Direction  of  head  movement 

20 

unused 

Output 

21 

/SEL2 

Select  drive  2 

Input 

22 

/INDEX 

Index  signal  from  drive 

23 

+12  volts 

2 

/CHNG 

4 

/INUSE1 

6 

/INUSE0 

8 

/INDEX 

10 

/SEL0 

12 

/SEL1 

14 

Unused 

16 

/MTR0 

18 

DIR 

20 

/STEP 

22 

/DKWD 

24 

/DKWE 

26 

/TKO 

28 

/WPRO 

30 

/DKRD 

32 

/SIDE 

34 

/RDY 

All  odd  pins  are  grounded. 
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Power  connector  for  the  internal  drive: 


+5  volts 
GND 
GND 
+12  volts 


The  disk  drive  connection  on  the  Amiga  is  compatible  with  the  Shugart 
bus.  It  allows  up  to  four  Shugart-compatible  disk  drives  to  be  connected. 
The  four  drives  are  selected  with  the  four  drive  selection  SELx  signals, 
where  x  is  the  number  of  the  drive  to  be  selected.  Two  of  the  drives  are 
intended  for  internal  installation  in  the  A3000,  so  only  the  lines  SEL2 
and  SEL3  are  available  on  the  external  drive  connector.  The  SELO  and 
SEL1  lines  are  connected  to  the  internal  drives  using  the  internal 
connector.  The  following  is  a  description  of  the  Shugart  bus  signals  on 
the  Amiga: 

SELX 

The  Amiga  uses  the  SELX  line  to  select  one  of  the  four  drives.  Except  for 
the  MTRX  and  DRES  lines,  all  other  signals  are  active  only  after  a  drive 
has  been  activated  with  the  corresponding  SELX  line. 

MTRX 

Normally  this  line  turns  on  all  the  drive  motors.  Since  this  is  not  practical 
in  a  system  that  can  have  up  to  four  drives,  each  drive  has  its  own  flip- 
flop  to  allow  the  motors  to  be  controlled  separately.  A  flip-flop  is  an 
electronic  component  that  can  store  a  data  bit.  When  a  given  drive's  SEL 
line  goes  low,  the  flip-flop  for  this  drive  takes  on  the  value  of  the  MTRX 
line.  The  output  of  the  flip-flop  is  connected  to  the  drive's  MTR  line.  So, 
for  example,  if  the  SELO  line  is  pulled  low  while  the  MTRX  line  is  at  0, 
the  motor  of  the  first  internal  disk  drive  turns  on. 

For  the  internal  drives  these  flip-flops  are  located  right  on  the 
motherboard.  Their  outputs  are  routed  via  an  OR  gate  to  the  MTR  line  of 
the  internal  floppy  connector.  There  are  separate  lines  for  the  LEDs: 
INUSEO  and  INUSE1.  An  additional  flip-flop  is  required  for  each  external 
drive. 
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RDY 

When  a  drive's  MTR  line  is  at  0,  the  RDY  (ReaDY)  line  is  used  to  signal 
the  Amiga  that  the  drive  motor  has  reached  its  optimum  speed  and  the 
drive  is  now  ready  for  read  or  write  accesses.  If  the  MTR  line  is  at  1, 
meaning  the  drive  motor  is  turned  off,  the  RDY  line  is  used  for  a  special 
identification  mode  (see  the  following). 

DRES 

The  DRES  (Drive  RESet)  line  is  connected  to  the  standard  Amiga  reset 
and  is  used  only  to  reset  the  motor  flip-flops  so  that  all  drive  motors  are 
turned  off. 

DKRD 

The  data  from  the  drive  selected  by  SELX  travels  over  the  DKRD  (DisK 
Read  Data)  line  to  the  DKRD  pin  on  Paula. 

DKWD 

The  DKWD  (DisK  Write  Data)  line  carries  data  from  Paula's  DKWD  pin  to 
the  current  drive,  where  it  is  then  written  to  the  diskette. 

DKWE 

The  DKWE  (DisK  Write  Enable)  line  switches  the  drive  from  read  to 
write.  If  the  line  is  high,  data  is  read  from  the  diskette.  If  it  is  low,  data  can 
be  written. 

SIDE 

The  SIDE  line  determines  which  side  of  a  diskette  will  be  selected  for 
reading  or  writing.  If  it  is  high,  side  0  (the  lower  read/write  head)  is 
active.  If  it  is  low,  side  1  is  active. 

WPRO 

The  WPRO  (Write  PROtect)  line  tells  the  Amiga  whether  the  inserted 
diskette  is  write-protected.  If  a  write-protected  diskette  is  in  the  drive,  the 
WPRO  line  is  0. 
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STEP 

A  rising  edge  on  the  STEP  line  (transition  from  low  to  high)  moves  the 
read/write  head  of  the  drive  one  track  in  or  out,  depending  on  the  state 
of  the  DIR  line.  The  STEP  signal  should  be  at  1  when  the  SEL  line  of  the 
activated  drive  is  set  back  to  high  or  there  may  be  problems  with  the 
diskette-change  detection. 

DIR 

The  DIR  (DIRection)  line  sets  the  direction  in  which  the  head  moves 
when  a  pulse  is  sent  on  the  STEP  line.  Low  means  that  the  head  moves  in 
toward  the  center  of  the  disk  and  high  indicates  movement  out  toward 
the  edge  of  the  disk.  Track  0  is  the  outermost  track  on  the  disk. 

TKO 

The  TKO  (TracK  0)  line  is  low  whenever  the  read/write  head  of  the 
selected  drive  is  on  track  0.  This  allows  the  head  to  be  brought  to  a 
defined  position. 

INDEX 

The  INDEX  signal  is  a  short  pulse  which  the  drive  delivers  once  per 
revolution  of  the  diskette,  between  the  start  and  end  of  a  track. 

CHNG 

With  the  CHNG  (CHaNGe)  line,  the  drive  notifies  the  Amiga  of  a  diskette 
change.  As  soon  as  the  diskette  is  removed  from  the  drive,  the  CHNG  line 
goes  to  0.  It  remains  at  0  until  the  computer  issues  a  STEP  pulse.  If  there 
is  a  diskette  in  the  drive  again  by  this  time,  CHNG  jumps  back  to  1. 
Otherwise  it  remains  at  0,  and  the  computer  must  issue  STEP  pulses  at 
regular  intervals  to  detect  when  a  diskette  has  again  been  inserted  in  the 
drive.  These  regular  STEP  pulses  are  the  cause  of  the  clicking  noise  the 
Amiga  drive  makes  when  no  diskette  is  inserted. 

INUSEO,  INUSEI 

The  INUSE  lines  exist  only  on  the  internal  floppy  connector.  If  INUSEO 
is  pulled  low,  drive  DFO  turns  its  LED  on.  INUSEI  serves  the  same 
purpose  for  drive  DF1. 
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To  recognize  whether  a  drive  is  connected  to  the  bus,  there  is  a  special 
drive  identification  mode.  This  involves  reading  a  serial  32-bit  data  word 
from  the  drive.  To  start  the  identification,  the  MTR  line  of  the  drive  in 
question  must  be  turned  on  briefly  and  then  off  again  (the  description  of 
the  MTRX  line  explains  how  this  is  done).  This  resets  the  serial  shift 
register  in  the  drive.  The  individual  data  bits  can  then  be  read  by  32 
iterations  of  the  following  procedure:  pull  the  SELX  line  low,  read  the 
value  of  the  RDY  line  as  a  data  bit,  then  return  the  SELX  line  to  high. 
The  first  bit  received  is  the  MSB  (Most  Significant  Bit)  of  the  data  word. 
Since  the  RDY  line  is  active  low,  the  data  bits  must  be  inverted. 

The  following  are  the  standard  definitions  for  external  drives: 

$0000  0000     No  drive  connected  (00) 

$FFFF  FFFF     Standard  Amiga  3  1/2°  drive         (11) 
$5555  5555     Amiga  5  1/4"  drive,   2x40  tracks    (01) 

As  you  can  see,  there  are  currently  so  few  different  identifications  that 
only  the  first  two  bits  must  be  read.  The  values  in  parentheses  are  the 
combinations  of  these  two  bits. 

As  mentioned  before,  all  the  lines  except  DRES  affect  only  the  drive 
selected  by  SELX.  Originally  the  MTRX  line  was  also  independent  of 
SELX,  but  the  Amiga  developers  changed  this  by  adding  the  motor  flip- 
flops. 

All  lines  on  the  Shugart  bus  are  active  low,  since  the  outputs  in  the 
Amiga  as  well  as  in  the  drives  themselves  are  provided  with  open- 
collector  drivers.  In  the  Amiga  these  are  type  7407  drivers. 

The  four  inputs  CHNG,  WPRO,  TK0  and  RDY  are  connected  in  this  order 
directly  to  PA4-PA7  of  CIA-A.  The  eight  outputs  STEP,  DIR,  SIDE, 
SELO,  SEL1,  SEL2,  SEL3  and  MTR  are  connected  through  the 
previously  mentioned  drivers  to  the  internal  and  external  drive 
connectors.  Since  these  drivers  are  non-inverting,  the  bits  from  the  CIAs 
are  inverted.  The  DKRD,  DKW  and  DKWE  lines  come  from  Paula. 

Except  for  the  MTRX  line  and  the  SEL  signals,  the  connections  to  the 
internal  and  external  floppies  are  the  same. 
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Installing  a  second  internal  drive 

As  mentioned  earlier,  a  second  internal  drive  can  be  installed  in  the 
A3000.  If  you  examine  the  connecting  cable  for  the  built-in  floppy,  you 
will  discover  a  second  plug  as  well  as  an  additional  power  supply 
connector. 

On  the  built-in  drive,  usually  next  to  the  plug  for  the  connecting  cable, 
there  is  a  switch  or  jumper  for  selecting  the  SELX  signal  to  which  the 
drive  should  react.  This  switch  should  be  set  to  SEL1,  since  SELO  is 
already  assigned  to  the  first  built-in  floppy.  The  drive  can  then  be 
installed  and  the  cable  connected. 

As  a  final  step,  the  Amiga  must  be  told  that  an  additional  drive  is  present. 
This  happens  using  the  RDY  line  in  the  special  identification  procedure 
described  earlier.  The  circuit  in  the  A3000  that  initiates  this  recognition 
procedure  for  the  two  internal  drives  is  connected  to  the  RDY  line  by 
means  of  the  J351  jumper.  This  jumper  is  located  on  the  left,  next  to  the 
rear  slot  for  the  perpendicular  bus  board,  directly  behind  Denise.  Simply 
switch  it  over  from  pins  2-3  to  1-2. 
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11.5.8        The  Game  Ports 


Use  as: 


Mouse  port 

Joystick 

Paddle 

Lightpen 

Input 

1 

V-pulse 

Up 

Unused 

Unused 

Input 

2 

H-pulse 

Down 

Unused 

Unused 

Input 

3 

VQ-pulse 

Left 

Left  button 

Unused 

Input 

4 

HQ-pulse 

Right 

Right  button 

Unused 

I/O 

5 

(Button  3) 

Unused 

Right  port 

Button 

I/O 

6 

Button  1 

Firebutton 

Unused 

LP  signal 

7 

+5  volts 

+5  volts 

+5  volts 

+5  volts 

8 

GND 

GND 

GND 

GND 

I/O 

9 

Button  2 

Unused 

Left  port 

Unused 

0  0  0  0  0 

0  0  0  B 

9-pin  female 


Game  port  pin  configuration 

The  game  ports  Game-Ports  are  inputs  for  input  devices  other  than  the 
keyboard,  such  as  a  mouse,  joystick,  trackball,  paddle  or  lightpen.  There 
are  two  game  ports,  the  left  one  being  designated  as  game  port  0  and  the 
right  as  game  port  1 .  The  pin  assignment  of  both  ports  is  identical,  except 
that  the  LP  line  is  present  only  on  game  port  0.  Internally  the  game  ports 
are  connected  to  CIA- A,  Agnus,  Denise  and  Paula.  The  individual  pins 
are  wired  as  follows: 
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Game  port  1: 


No. 

Chip 

Pin 

1 

2 

3 

4 

5 

6 

and 

9 

Denise 

Denise 

Denise 

Denise 

Paula 

CIA-A 

Agnus 

Paula 

MOV   (via  multiplexer) 
MOH   (via  multiplexer) 
M1V  (via  multiplexer) 
M1H   (via  multiplexer) 
POY 
PA6 

POX 

Game  port  2: 


No. 

Chip 

Pin 

1 
2 
3 
4 
5 

Denise 
Denise 
Denise 
Denise 
Paula 

MOV   (via  multiplexer) 
MOH   (via  multiplexer) 
M1V   (via  multiplexer) 
M1 H   (via  multiplexer) 

P1Y                               ! 

6 

CIA-A 

PA7 

and 
9 

Agnus 
Paula 

LP 
P1X 

The  function  of  the  multiplexers  was  explained  previously.  The  pin 
assignments  for  the  various  input  devices  were  chosen  so  that  almost  all 
standard  joysticks,  mice,  paddles  and  lightpens  can  be  used.  The  button 
line  is  usually  connected  to  a  switch  that  is  pressed  when  the  lightpen 
touches  the  screen. 

The  LP  line  is  the  actual  lightpen  signal,  which  is  generated  by  the 
electronics  in  the  pen  when  the  electron  beam  passes  its  tip.  On  the 
A 1000,  the  lightpen  line  was  connected  to  game  port  0.  This  meant  that 
you  had  to  use  a  different  mouse  connection  or  disconnect  the  mouse 
entirely  in  order  to  use  a  lightpen.  Because  of  this  disadvantage,  the 
lightpen  on  the  A3000  is  normally  connected  to  port  1 .  Jumper  J352  is 
used  to  select  where  the  lightpen  will  go.  Use  the  jumper  to  connect  pins 
2  and  3,  and  the  lightpen  will  go  to  game  port  1. 

All  the  lines  labeled  button  and  the  four  directions  for  the  joystick  are 
active  low.  The  various  input  devices  contain  switches  that  connect  their 
inputs  to  ground  (GND).  A  high  signal  on  the  input  means  an  open 
switch,  while  a  closed  switch  generates  a  low. 
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Variable  resistors  (potentiometers)  can  be  connected  to  the  POX,  POY, 
P1X  and  P1Y  analog  inputs.  Their  value  should  be  470  KOhms  and  they 
should  be  connected  between  the  corresponding  inputs  and  +5  volts. 

The  two  fire-button  lines  connected  to  CIA-A  can  naturally  also  be 
programmed  as  outputs.  Don't  overwrite  the  lowest  bit  of  the  port 
register;  otherwise  the  system  crashes  (PA0:OVL).  The  section  on 
programming  the  custom  chips  explains  how  the  game  port  lines  are  read. 

The  +5  volt  line  on  the  two  game  ports  is  not  connected  directly  to  the 
Amiga  power  supply.  A  current-protection  circuit  is  inserted  in  these 
lines  which  limits  the  short-term  peak  current  to  700  mA  and  the 
operating  current  to  400  mA. 
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11.5.9 


The  Zorro  Bus 


Configuration  of  the  100-pin  expansion  slot:  Zorro  II 


1 

GND 

2 

GND 

3 

GND 

4 

GND 

5 

+5  volts 

6 

+5  volts 

7 

/OWN 

8 

-5  volts 

9 

/SLAVEn 

10 

+12  volts 

11 

/CFGOUTn 

12 

CFGINn 

13 

GND 

14 

/C3 

15 

CDAC 

16 

/C1 

17 

/OVR 

18 

XRDY 

19 

/INT2 

20 

-12  volts 

21 

A5 

22 

/INT6 

23 

A6 

24 

A4 

25 

GND 

26 

A3 

27 

A2 

28 

A7 

29 

A1 

30 

A8 

31 

FCO 

32 

A9 

33 

FC1 

34 

A10 

35 

FC2 

36 

A11 

37 

GND 

38 

A12 

39 

A13 

40 

/EINT7 

41 

A14 

42 

/EINT5 

43 

A15 

44 

/EINT4 

45 

A16 

46 

/BERR 

47 

A17 

48 

/VPA 

49 

GND 

50 

E 

51 

/VMA 

52 

A18 

53 

/RES 

54 

A19 

55 

/HLT 

56 

A20 

57 

A22 

58 

A21 

59 

A23 

60 

/BRn 

61 

GND 

62 

/BGACK 

63 

PD15 

64 

/BGn 

65 

PD14 

66 

/DTACK 

67 

PD13 

68 

/R/W 

69 

PD12 

70 

/LDS 

71 

PD11 

72 

/UDS 

73 

GND 

74 

/AS 

75 

PDO 

76 

PD10 

77 

PD1 

78 

PD9 

79 

PD2 

80 

PD8 

81 

PD3 

82 

PD7 

83 

PD4 

84 

PD6 

85 

GND 

86 

PD5 

87 

GND 

88 

GND 

89 

GND 

90 

GND 

91 

GND 

92 

7MHz 

93 

DOE 

94 

/BUSRST 

95 

/GBG 

96 

/EINT1 

97 

reserved 

98 

reserved 

99 

GND 

100 

GND 
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In  the  previous  chart  "n"  equals  the  number  of  expansion  slots  (1-4). 

The  set  of  four  100-pin  expansion  slots,  called  the  Zorro  bus,  is  located 
on  the  upright-mounted  board  in  the  center  of  the  A3000.  The  slots  can 
accept  all  types  of  expansion  cards.  On  the  A2000  this  usually  refers  to 
hard  disk  controllers  and  RAM  expansions,  but  on  the  A3000  is  more 
likely  to  mean  networks,  high-resolution  graphic  cards,  etc. 

For  this  reason  the  bus  specifications  have  been  thoroughly  revised. 
Expansion  slots  in  the  A3000  can  now  operate  in  two  distinct  modes: 
Zorro  II  compatible  (as  in  the  A2000)  or  the  new  Zorro  III  standard. 

The  Zorro  II  mode  is  based  mainly  on  the  signals  of  the  68000: 


A0-A23 

PD0-PD15 
IPLO  -  IPL2 
FCO  -  FC2 

/AS,  /UDS,  /LDS,  /R/W, 
/DTACK,  A/MA,  A/PA 
/RES,  /HLT,  /BERR,  /BG, 
/BGACK,  /BR,  E 


Address  bus  (24  bits,  i.e.,  16  Megabyte 
address  space) 
Processor  data  bus 
Processor  interrupt  lines 
Function  code  lines  from  the  68000 

Bus  control  lines 

Miscellaneous  control  lines  from  the  68000 


The  remaining  signals  have  the  following  functions: 

INT2andINT6: 

These  two  lines  are  connected  to  the  Paula  pins  with  the  same  names. 
They  are  used  to  generate  a  level  2  or  level  6  interrupt. 

CD  AC,  IC3,  /CI,  7M  and  28M: 

These  are  the  various  Amiga  clock  signals.  The  clock  signals  CCK  and 
CCKQ  are  generated  by  Agnus  and  serve  as  base  clock  signals  for 
Agnus,  Denise,  Paula  and  the  chip  RAM. 
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13    5     7 


2     4    6     8 


79  81  83   85 


80  82  84   86 


86-pin  printed  circuit  connector 
(Amiga  500/Amiga  1000) 


Pin  configuration  of  the  expansion  port 


/OVR 


With  /OVR  low  the  DTACK  signal  produced  by  Gary  can  be  disabled  for 
the  memory  range  from  $200000  to  $9FFFFF. 

IXRDY 

This  signal  serves  a  similar  purpose  to  /OVR.  If /XRDY  is  pulled  low  less 
than  60  nanoseconds  after  /AS,  Gary  delays  the  /DTACK  signal  until 
/XRDY  again  goes  high.  This  allows  the  use  of  slow  expansion  cards  that 
cannot  respond  without  wait  states. 

/BUSRES 

This  is  a  buffered  reset  signal.  While  the  Amiga  can  also  be  reset  from  an 
expansion  card  with  the  RES  circuit,  the  /BUSRES  line  is  intended  only 
for  resetting  the  card  itself.  Normally  you  would  not  want  to  reset  the 
Amiga  from  a  card,  and  should  therefore  only  use  the  /BUSRES  line. 

ISLAVEn 

Every  slot  has  its  own  /SLAVE  line.  An  expansion  card  must  set  /SLAVE 
to  low  as  soon  as  it  recognizes  an  address  that  is  valid  for  it,  so  that  the 
data  and  address  buffers  can  be  correctly  switched.  If  more  than  one  card 
sets  /SLAVE  to  low,  Gary  generates  a  bus  error.  The  same  holds  true  if  a 
card  outside  the  ranges  $200000-$B7FFFF  and  $E80000-$EFFFFF  has 
/SLAVE  set  to  low. 
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ICFG1N  and  ICFGOUT 

The  /CFGOUT  (ConFiG-OUT)  line  of  one  slot  is  always  connected  to  the 
/CFGIN  (ConFiG-IN)  line  of  the  next.  Each  card  is  configured  as  soon  as 
the  /CFGIN  line  of  its  slot  is  low.  When  the  autoconfiguration  of  a  card  is 
complete,  it  sets  its  /CFGOUT  output  to  low  to  allow  configuration  of  the 
card  in  the  next  slot  to  proceed. 

DOE 

This  signal  comes  from  Buster  and  tells  the  active  expansion  card  that  it 
may  activate  its  data  drivers.  This  prevents  data  collisions. 

IBRn,  IBGn  and  IBGACK 

With  these  lines  a  card  can  take  over  the  bus,  in  effect  becoming  the 
DMA  controller.  The  ability  to  do  this  is  required,  for  example,  by  a  fast 
network  card.  Bus  control  is  assumed  as  follows:  the  card  pulls  /BR  low 
->,  the  processor  responds  with  /BG  ->,  the  card  pulls  /BGACK  low  and 
returns  /BR  to  high.  It  now  owns  the  bus  until  it  returns  /BGACK  to 
high. 

What  happens,  though,  if  two  cards  pull  /BR  low  at  the  same  instant?  To 
avoid  problems,  each  slot  has  its  own  /BR  and  /BG  signals.  If  more  than 
one  slot  activates  its  /BR  signal,  Buster  sees  the  slot  with  the  lowest 
number  (the  one  nearest  the  coprocessor  slot)  first,  and  passes  the  /BR  on 
to  the  68030.  The  /BG  response  is  returned  by  Buster  to  this  same  slot, 
which  becomes  bus  master  and  pulls  /BGACK  low.  The  other  slots  that 
have  their  /BR  lines  low  must  wait  until  the  one  currently  active  has 
finished  its  DMA. 

/OWN 

A  card  must  pull  this  line  low  when  it  has  assumed  the  role  of  bus  master 
as  previously  described.  This  is  necessary  to  reverse  the  direction  of  the 
data  or  address  buffer,  since  the  bus  master  generating  the  addresses  is 
now  on  the  other  side  of  the  buffer. 

IGBG 

This  is  the  original  /BG  from  the  processor. 
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The  interrupt  lines  /EINT1,  IEINT4,  IEINT5  and  IEINT7 

These  lines  generate  the  corresponding  level  interrupts.  Unlike  the  /INT2 
and  /INT6  lines  of  the  expansion  port,  they  cannot  be  disabled  using 
Paula. 

Also  on  the  Zorro  bus  are  the  different  operating  voltages  of  the  A3000: 
+/-  5  and  12  volts. 

The  previous  description  of  the  pin  configuration  and  functions  refers  to 
operation  of  the  expansion  bus  in  Zorro  II  mode.  The  A3000  also 
recognizes  a  different  type  of  bus  protocol,  the  new  Zorro  III  standard. 

When  you  insert  an  expansion  card  into  the  A3000,  the  expansion 
library  contained  in  Kickstart,  using  the  autoconfiguration  information 
on  the  expansion,  checks  to  see  whether  it  is  a  Zorro  II  or  a  Zorro  III 
card.  If  the  library  recognizes  a  Zorro  II  card,  for  example,  one  developed 
also  for  the  A2000  circuitry,  the  bus  behaves  as  previously  described, 
that  is,  compatible  to  the  A2000  expansion  slots. 

If  the  card  is  determined  to  be  a  Zorro  III  card,  the  Amiga  operating 
system  assigns  it  an  address  outside  the  Amiga's  former  16-Megabyte 
address  space.  The  bus  controller  treats  processor  accesses  to  addresses 
within  the  first  16  Meg  as  Zorro  II,  and  beyond  that  as  Zorro  III. 

How  does  the  Zorro  III  standard  differ  from  Zorro  II? 

Zorro  III  is  a  completely  new  concept.  Although  the  same  100-pin  slots 
are  used,  the  assignments  of  many  of  the  lines  have  changed.  The 
essential  features  of  Zorro  III  are  as  follows: 

•       A  full  32  bits  for  data  and  address  bus 

The  Zorro  III  bus  is  a  32-bit  bus  system,  fully  supporting  the 
capabilities  of  the  68030.  Since  a  slot's  100  pins  are  not  sufficient 
for  both  data  and  address  lines  (2  x  32),  these  lines  are  multiplexed. 
To  initiate  an  access,  the  Amiga  places  the  32  address  bits  on  the 
bus.  Then,  using  a  specific  control  signal,  it  tells  the  Zorro  III 
expansion  card  to  store  this  address.  After  that  the  address  lines 
serve  as  data  lines.  Address  bits  0-7  are  not  multiplexed,  but  rather 
remain  stable  throughout  the  access  process. 
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Asynchronous  bus  control 

The  speed  of  the  old  Zorro  II  bus  was  limited  by  the  timing  of  the 
68000.  Bus  transfer  could  not  execute  faster  than  a  68000  memory 
access  at  a  clock  frequency  of  7.14  MHz.  The  Zorro  III  timing  is 
asynchronous,  so  the  speed  does  not  depend  on  how  fast  the 
Amiga  or  card  hardware  may  be  (of  course  there  are  models  with  far 
higher  clock  frequencies  than  previously  thought  possible). 

Enhanced  interrupt  capabilities 

In  the  Zorro  III  bus,  expansions  can  finally  fully  utilize  the  interrupt 
capabilities  of  the  68030,  meaning  that  a  card  can  use  its  own 
interrupt  vectors  (see  the  section  on  68030). 
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11.6  The  Keyboard 


The  Amiga  keyboard  is  an  intelligent  keyboard.  It  has  its  own 
microprocessor,  which  handles  the  time-consuming  job  of  reading  the 
keys  and  returning  complete  key  codes  to  the  Amiga.  The  following 
figure  shows  the  layout  of  the  keys  and  their  codes  for  the  German  and 
American  versions  of  the  keyboard.  As  you  can  see,  the  codes  do  not 
correspond  to  the  ASCII  standard.  The  keyboard  only  returns  raw  key 
codes,  which  the  operating  system  converts  to  ASCII  using  a  translation 
table  called  the  key  map.  There  is,  however,  a  system  to  the  raw  key  code 
assignments: 

$00-$3F  Codes  for  the  letters,  digits  and  punctuation  characters. 
Their  assignments  correspond  to  the  arrangement  on  the 
keyboard. 


$40-$4F        Codes  for  the  standard  special  keys  like  I  Spacebar  I ,  [Enter!. 


Iiab  1  etc. 
$50-$5F        Function  keys  and  HELP. 


$60-$67        Keys  for  selecting  keyboard  control  levels  (1  Shift  I.  Amiga, 

(AJQ  and  fcFFTll 
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American  keyboard 


EM         f\ 

45  SO 


p IB rr. m m. p ps p r 

|     51     |      52    I      S3     I    54  55     I      56     I     57    I       58 


wmpn 


1 


"'    f     Y     F     I      I      I      V 

42     I  10    I  11    I     12  I     13         14         15  I 

HIM  ft   '   18  '      II1      It'1      »'      B1 


P  31    132    133     [34     f35    Im     In     l3e       39  1/ 


I    25         26   I    27        28    I*  29       '  2A  I 


67  ■      65     I 


3D 

3E 

3P 

'  2D 

2E 

2F 

in 

IE 

IF 

OF 

3C 

ih     1           43 

German  keyboard 


•  JO  f  31 

>  r  66 


! P R f IS IS IB p— 

"   I   50   I   51   I   52  I   5j     54   I   55  I  56 

00  |   01  T  02  I   03   I  04  T  05  I  06     07 1   00  I  09  \     0A    00 1' OC  I 

*   r   r    i     r    r    l"    I*    r  h    i   l    l 

43      I     10  11  12     I     13  14    I      15  16  I   17  I     10     I  19         1A   I"    IB 

*•  bs  f     r      r     r     i     \     r     \    t  t    I  \ 

J   ^2    20     21      22    23     24  I  25  I   26  27    20    29   2A  P  2B 


EE 


E 


r 


3D 

3£ 

5F 

2D 

2E 

IP 

ID 

IE 

IF 

OF 

3C 

1A      1             43 

The  keyboard     ' 

The  keyboard  processor  can  do  more  than  read  the  keys.  It  can 
distinguish  between  when  a  key  is  pressed  and  when  it  is  released.  As 
you  can  see,  all  keyboard  codes  are  only  7  bits  (values  range  from  $00- 
$7f)-  The  eighth  bit  is  the  KEYup/down  flag.  It  is  used  by  the  keyboard 
to  tell  the  computer  whether  the  key  was  just  pressed  or  released.  If  the 
eighth  bit  is  0,  this  means  that  the  key  was  just  pressed  (KEYdown).  If  it 
is  1,  then  the  key  was  just  released  (KEYup).  This  way  the  Amiga  always 
knows  which  keys  are  currendy  pressed. 

The  keyboard  can  thus  be  used  for  other  purposes  that  require  various 
keys  to  be  held  simultaneously.  This  includes  music  programs,  for 
example,  which  use  the  keyboard  for  playing  polyphonically. 
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One  exception  is  the  leaps  Lock  >  key.  The  keyboard  simulates  a  toggle 
switch  with  this  key.  The  first  time  it  is  pressed,  it  engages  and  the  LED 
goes  on.  It  does  not  disengage  until  it  is  pressed  again.  The  LED  then 
turns  off.  This  behavior  is  also  reflected  in  the  KEYup/down  flag.  If 
(caps  Lock  \  is  pressed,  the  LED  turns  on,  and  the  key  code  for  leaps  Lock  I 
is  sent  to  the  computer  along  with  a  cleared  eighth  bit  to  show  that  a  key 
was  just  pressed.  When  the  key  is  released,  no  KEYup  code  is  sent,  and 
the  LED  stays  on.  Not  until  leaps  Lock  \  is  pressed  again  is  a  KEYup  code 
sent  (with  a  set  eighth  bit),  and  the  LED  turns  off. 

11 .6.1        Data  Transfer  from  the  Keyboard 


Ct.lt 

LrTJ~xrxr~UH_rTJ~i_r 

max.           . 

14  5ns     »Jn' 
7SJ1S 

I  \6    X5X4X3X2X1X°X7/ 

~~ L_J- 

Handshake 
signal 

60|iB 

Data  transfer  from  the  keyboard 

The  keyboard  is  connected  to  the  Amiga  by  a  four-line  coiled  cable.  Two 
of  the  lines  are  used  to  supply  power  to  the  keyboard  electronics  (5 
volts).  The  entire  data  transfer  takes  place  over  the  remaining  two  lines. 
One  of  these  lines  is  used  for  data  (KDAT),  and  the  other  is  the  clock  line 
(KCLK).  Inside  the  Amiga,  KDAT  is  connected  to  the  serial  input  SP,  and 
KCLK  is  connected  to  the  CNT  pin  of  CIA-A.  The  data  transfer  is 
unidirectional.  It  always  runs  from  the  keyboard  to  the  computer.  The 
processor  in  the  keyboard  places  the  individual  data  bits  on  the  data  line 
(KDAT),  accompanied  by  20  microsecond-long  low  pulses  on  the  clock 
line  (KCLK).  Between  the  individual  clock  pulses  are  40  microsecond- 
long  pauses.  This  amounts  to  a  transfer  time  of  60  microseconds  for  each 
bit,  or  480  microseconds  per  8-bit  byte.  The  resulting  data  transfer  rate  is 
16666  baud  (bits/second). 

After  the  last  bit  has  been  sent,  the  keyboard  waits  for  a  handshake  pulse 
from  the  computer.  The  Amiga  sends  this  signal  by  pulling  the  KDAT  line 
low  for  at  least  75  microseconds.  The  exact  process  can  be  seen  in  above 
the  diagram.  The  bits  are  not  sent  in  the  usual  order  7-6-5-4-3-2-1-0,  but 
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rotated  one  bit  position  to  the  left:  6-5-4-3-2-1-0-7.  For  example,  the  key 
code  for  "J"  with  the  eighth  bit  set  is  101001 10,  and  after  rotation  it  is 
01001 101.  The  KEYup/down  flag  is  always  the  last  bit  sent. 

The  data  line  is  active  low.  This  means  that  a  0  is  represented  by  a  high 
signal  and  a  1  by  a  low. 

The  CIA  shift  register  in  the  Amiga  reads  the  current  bit  on  the  SP  line  at 
each  clock  pulse.  After  eight  clock  pulses  the  CIA  has  received  a 
complete  data  byte.  The  CIA  then  normally  generates  a  level  2  interrupt, 
which  causes  the  operating  system  to  do  the  following: 

•  Read  the  serial  data  register  in  the  CIA. 

•  Invert  and  right-rotate  the  byte  to  get  the  original  key  code  back. 

•  Output  the  handshake  pulse. 

•  Process  the  received  code. 

Synchronization 

In  order  to  have  an  error-free  data  transfer,  the  timing  of  the  sender  and 
receiver  must  match.  The  bit  position  for  the  serial  transfer  must  be 
identical  for  both.  Otherwise  the  keyboard  may  have  sent  all  eight  bits, 
while  the  serial  port  of  the  CIA  is  still  somewhere  in  the  middle  of  the 
byte.  Such  a  loss  of  synchronization  occurs  whenever  the  Amiga  is 
turned  on  or  the  keyboard  is  plugged  into  a  running  Amiga.  The 
computer  has  no  way  of  recognizing  improper  synchronization.  This  task 
is  handled  by  the  keyboard. 

After  each  byte  is  sent,  the  keyboard  waits  a  maximum  of  145 
milliseconds  for  the  handshake  signal.  If  it  does  not  occur  in  this  time,  the 
keyboard  processor  assumes  that  a  transfer  error  has  occurred  and  enters 
a  special  mode  in  which  it  tries  to  restore  the  lost  synchronization.  It 
sends  a  1  on  the  KDAT  line  together  with  a  clock  pulse  and  waits 
another  145ms  for  the  synchronization  signal.  It  repeats  this  until  it 
receives  a  handshake  signal  from  the  Amiga.  Synchronization  is  now 
restored. 

The  data  byte  received  by  the  Amiga  is  incorrect,  however.  The  state  of 
the  first  seven  bits  is  uncertain.  Only  the  last  bit  received  is  definitely  a  1, 
because  the  keyboard  processor  only  outputs  l's  during  the  procedure 
described  above.  Since  this  last  bit  is  the  KEYup/down  flag,  the  incorrect 
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code  is  always  a  KEYup  code,  or  a  released  key.  This  causes  less  program 
disturbances  than  if  an  incorrect  KEYdown  code  had  been  sent.  This  is 
why  each  byte  is  rotated  one  bit  to  the  left  before  it  is  sent,  so  that  the 
KEYup/down  flag  is  always  the  last  bit  sent. 

Special  codes 

There  are  some  other  special  cases  in  transmission,  which  the  keyboard 
tells  the  Amiga  through  special  key  codes. 

The  following  table  contains  all  possible  special  codes: 


Code      Meaning 


$F9 
$FA 
$FC 
$FD 
$FE 


Last  key  code  was  incorrect 
Keyboard  buffer  is  full 
Error  in  keyboard  self-test 
Start  of  keys  held  on  power  up 
End  of  keys  held  on  power  up 


$F9 

The  $F9  code  is  always  sent  by  the  keyboard  after  a  loss  of 
synchronization  and  subsequent  resynchronization.  This  is  how  the 
Amiga  knows  that  the  last  key  code  was  incorrect.  After  this  code  the 
keyboard  retransmits  the  lost  key  code. 

$FA 

The  keyboard  has  an  internal  buffer  of  10  characters.  When  this  buffer  is 
full,  it  sends  a  $FA  to  the  computer  to  signal  that  it  must  empty  the  buffer 
or  lose  characters. 

$FC 

After  it  is  turned  on,  the  keyboard  processor  performs  a  self-test.  This  is 
indicated  by  the  brief  lighting  of  the  [caps  Lock!  LED.  If  it  discovers  an 
error,  it  sends  a  $FC  to  the  Amiga  and  then  goes  into  an  endless  loop  in 
which  it  flashes  the  LED. 

$FD  &  $FE 

If  the  self-test  was  successful,  the  keyboard  transmits  all  the  keys  that 
were  held  when  the  computer  was  powered  up.  To  tell  the  computer  this, 
it  starts  the  transmission  with  the  $FD  code. 
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Then  follow  the  codes  of  the  keys  pressed  on  power  up,  terminated  by 
the  code  $FE.  After  that  normal  transmission  begins. 

If  no  keys  were  pressed,  $FD  and  $FE  are  sent  in  immediate  succession. 

Reset  through  the  keyboard 

The  keyboard  can  also  generate  a  reset  on  the  Amiga.  If  the  two  Amiga 
keys  and  the  Ictnl  key  are  pressed  simultaneously,  the  keyboard 
processor  pulls  the  KCLK  line  low  for  about  0.5  seconds.  This  causes  the 
reset  circuit  in  the  Amiga  to  generate  a  processor  reset.  After  at  least  one 
of  these  keys  has  been  released,  the  keyboard  also  resets  itself.  This  can 
be  seen  by  the  flashing  of  the  I  caps  lock  I  LED. 
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11.7   Programming  the  Hardware 

The  previous  sections  involved  closer  looks  at  the  hardware  structure  of 
the  Amiga.  The  following  pages  show  how  the  three  custom  chips  are 
programmed.  Now  we'll  begin  an  introduction  to  software,  especially 
concerning  the  creation  of  graphics  and  sound. 

To  successfully  program  the  Amiga  at  the  machine  level,  you  must  know 
the  memory  layout  and  the  addresses  of  the  individual  hardware 
registers. 

11.7.1        The  Memory  Layout 

The  first  figure  shows  the  normal  memory  configuration  of  the  Amiga  as 
it  appears  after  booting.  The  entire  address  range  of  the  68030  comprises 
4  gigabytes  (addresses  from  0  to  $FFFFFFFF).  However,  this  huge 
address  space  is  not  uniformly  allocated.  In  the  lower  16  megabytes, 
space  is  at  a  premium  because  this  is  where  all  the  system  components 
that  existed  in  the  A2000  are  located.  The  remainder  is  used  for  the 
internal  fast  RAM,  the  new  chips,  including  the  SCSI  DMA  controller, 
and  the  Zorro  III  expansions  area. 

RAM 

In  the  Amiga  there  is  a  distinction  between  chip  RAM  and  fast  RAM. 
The  chip  RAM  is  used  by  the  custom  chips,  Agnus,  Denise  and  Paula,  to 
store  graphics  and  sound  data.  One  megabyte  of  this  RAM  comes 
factory-installed,  and  sockets  for  adding  a  second  megabyte  are 
included. 

The  internal  fast  RAM  is  available  only  to  the  processor,  the  SCSI  DMA 
chip  and  any  expansion  cards.  Agnus  cannot  access  it. 

Using  the  new  4-megabit  RAM  chips,  the  Amiga  can  be  upgraded  to  a 
maximum  of  1 6  megabytes  of  internal  RAM. 

When  equipping  the  A3000  with  RAM,  first  you  must  decide  whether  to 
use  1-Mbit  or  4-Mbit  RAM  chips.  The  two  types  cannot  be  mixed.  The 
jumper  J852  selects  the  chip  capacity: 
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J852  connecting  pins  2  and  3:  1  Mbit,  organized  as  256  K  x  4 
J852  connecting  pins  1  and  2:  4  Mbit,  organized  as  1  M  x  4 


If  you  are  upgrading  with  4-Mbit  RAM  chips,  the  eight  factory-installed 
chips  must  be  removed.  However,  they  can  be  used  to  expand  the  chip 
RAM. 

The  RAM  is  organized  in  four  banks  of  eight  chips  each.  The  socket 
assignments  of  the  banks  are  as  follows: 


BankO: 

U850  -  U857  or  U850D  -  U857D 

Bankl: 

U858  -  U865 

Bank  2: 

U866  -  U873 

Bank  3: 

U874-U881 

$01000000 

$00F00000 
$00E80000 

$00000000 
$00B80000 

$00A00000 


$00200000 
$00000000 


ROM 


Area  For 
Autocontiguration 


Custom  chips 


Zorro  I 


Area  For  Expansion 


Zorro  II 

Area  for 

Memory  Expansion 


Chip-RAM 


Zorro  III 
Expansion  area 


Fast  RAM 


Amiga  3000 
Register  area 


$80000000 


$10000000 


$08000000 


$01000000 


$00000000 


RAMIROM  allocation  in  the  Amiga 
The  following  types  of  RAM  chips  can  be  used: 

xx4256-80  (1  Mbit)  or  xx4400-80  (4  Mbit)  ZIP-mounted  (these  are  the 
upright  as  opposed  to  the  flush-mounted  DIL  chips). 
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For  greater  speed,  static-column  RAM  chips  can  also  be  used:  xx4258- 
80  or  xx4402-80. 

These  enable  the  68030  CPU  to  operate  in  burst  mode,  supplying  the 
internal  cache  with  new  data  at  a  rate  faster  than  that  of  normal  data 
access  (this  mode  is  turned  on  by  the  SETCPU  command  in  the  CLI). 

The  base  address  of  fast  RAM  with  a  1  megabyte  configuration  is 
$07F00000.  As  memory  is  added,  the  base  address  shifts  down 
accordingly  (e.g.,  $07D00000  with  4  megabytes). 

The  CIAs 

Details  about  the  CIAs  can  be  found  in  Section  11.3.  The  following  are 
the  addresses  of  the  individual  registers: 


CIA-A 

CIA-B 

Name 

Function 

$BFE001 

$BFD000 

PA 

Port  register  A 

$BFE101 

$BFD100 

PB 

Port  register  B 

$BFE201 

$BFD200 

DDRA 

Data  direction  register  A 

$BFE301 

$BFD300 

DDRB 

Data  direction  register  B 

$BFE401 

$BFD400 

TALO 

Timer  A  low  byte 

$BFE501 

$BFD500 

TAHI 

Timer  A  high  byte 

$BFE601 

$BFD600 

TBLO 

Timer  B  low  byte 

$BFE701 

$BFD700 

TBHI 

Timer  B  high  byte 

$BFE801 

$BFD800 

E.  LSB 

Event  counter  bits  0-7 

$BFE901 

$BFD900 

E.MID 

Event  counter  bits  8-1 5 

$BFEA01 

$BFDA00 

E.  MSB 

Event  counter  bits  1 6-24 

$BFEB01 

$BFDB00 

— 

Unused 

$BFEC01 

$BFDC00 

SP 

Serial  port  register 

$BFED01 

$BFDD00 

ICR 

Interrupt  control  register 

$BFEE01 

$BFDE00 

CRA 

Control  register  A 

$BFEF01 

$BFDF00 

CRB 

Control  register  B 

The  custom  chips 

The  various  custom  chip  registers  occupy  a  510-byte  area.  Each  register 
is  2  bytes  (one  word)  wide.  All  registers  are  on  even  addresses. 

The  base  address  of  the  register  area  is  at  $DFF000.  The  effective  address 
of  a  register  is  then  $DFF000  +  register  address.  The  following  list  shows 
the  names  and  functions  of  the  individual  chip  registers.  Most  of  the 
register  descriptions  are  unfamiliar  now  since  we  haven't  discussed  the 
functions  of  the  registers,  but  this  list  will  give  you  an  overview  and  will 
later  serve  as  a  reference. 
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There  are  four  types  of  registers: 

r  (Read) 

This  register  can  only  be  read. 

w  (Write) 

This  register  can  only  be  written. 

s  (Strobe) 

An  access  to  a  register  of  this  type  causes  a  one-time  action  to  occur  in 
the  chip.  The  value  of  the  data  bus  (i.e.,  the  word  to  be  written  to  the 
register)  is  irrelevant.  These  registers  are  usually  accessed  only  by  Agnus. 

er  (Early  Read) 

A  register  designated  as  early  read  is  a  DMA  output  register.  It  contains 
the  data  to  be  written  into  the  chip  RAM  through  DMA.  There  are  two 
such  registers  (DSKDATR  and  BLTDDAT  -  output  registers  for  the  disk 
and  the  Blitter).  They  are  accessed  only  by  the  DMA  controller  in  Agnus, 
when  their  contents  are  written  into  the  chip  RAM.  The  processor 
cannot  access  these  registers. 

A,D,P 

These  three  letters  represent  the  three  chips  Agnus,  Denise  and  Paula. 
They  indicate  in  which  chip  the  given  register  is  found.  It  is  also  possible 
for  a  register  to  be  located  in  more  than  one  chip.  On  such  a  write  access, 
the  value  is  then  written  into  two  or  even  all  three  chips.  This  is  the  case 
when  the  contents  of  a  given  register  are  needed  by  more  than  one  chip. 

For  the  programmer  it  is  unimportant  where  the  registers  are  located.  The 
entire  area  can  be  treated  as  one  custom  chip.  The  programmer  needs  to 
know  only  the  address  and  function  of  the  desired  register. 

p,d 

A  lowercase  "d"  means  that  this  register  is  accessible  only  by  the  DMA 
controller.  Registers  preceded  by  a  lowercase  "p"  are  used  only  by  the 
processor  or  the  Copper.  If  both  letters  precede  a  register,  it  means  that  it 
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is  usually  accessed  by  the  DMA,  but  also  by  the  processor  from  time  to 
time. 

Number  of  registers:  227 


Registers  are  normally  accessed  only  by  the  DMA  controller:  54 
Base  address  of  the  register  area:  $DFF000 


Name 

Reg.addr. 

Chip 

R/W 

p/d 

Function 

BLTDDAT 

000 

A 

er 

d 

Blitter  output  data  (from  Blitter  to  RAM) 

D MACON R 

002 

AP 

P 

Read  DMA  control  register 

VPOSR 

004 

A 

P 

MSB  of  vertical  position 

VHPOSR 

006 

A 

P 

Vertical  and  horizontal  beam  position 

DSKDATR 

008 

P 

er 

d 

Disk  read  data  (from  disk  to  RAM) 

JOYODAT 

00A 

D 

P 

Joystick/mouse  position  game  port  0 

JOY1 DAT 

OOC 

D 

P 

Joystick/mouse  position  game  port  1 

CLXDAT 

00E 

D 

P 

Collision  register 

ADKCONR 

010 

P 

P 

Read  audio/disk  control  register 

POTODAT 

012 

P 

P 

Read  potentiometer  game  port  0 

POT1DAT 

014 

P 

P 

Read  potentiometer  game  port  1 

POTGOR 

016 

P 

P 

Read  pot.  port  data 

SERDATR 

018 

P 

P 

Read  serial  port  and  status 

DSKBYTR 

01A 

P 

P 

Read  disk  data  byte  and  status 

INTENAR 

01C 

P 

P 

Read  interrupt  enable 

INTREQR 

01 E 

P 

P 

Read  interrupt  request 

DSKPTH 

020 

A 

w 

P 

Disk  DMA  address  bits  16-20 

DSKPTL 

022 

A 

w 

P 

Disk  DMA  address  bits  1-15 

DSKLEN 

024 

P 

w 

P 

Disk  DMA  block  length 

DSKDAT 

026 

P 

w 

d 

Disk  write  data  (from  RAM  to  disk) 

REFPTR 

028 

A 

w 

d 

Refresh  counter 

VPOSW 

02A 

A 

w 

P 

Write  MSB  of  vertical  beam  position 

VHPOSW 

02C 

A 

w 

P 

Write  vertical  and  horizontal  beam  position 

COPCON 

02E 

A 

w 

P 

Copper  control  register 

SERDAT 

030 

P 

w 

P 

Write  serial  data  and  stop  bits 

SERPER 

032 

P 

w 

P 

Serial  port  control  register  and  baud  rate 

POTGO 

034 

P 

w 

P 

Write  pot.  port  data  and  start  bit 

JOYTEST 

036 

D 

w 

P 

Write  in  both  mouse  counters 

STREQU 

038 

D 

s 

d 

Horizontal  sync  with  VB  and  equal  frame 

STRVBL 

03A 

D 

s 

d 

Horizontal  sync  with  vertical  blank 

STRHOR 

03C 

DP 

s 

d 

Horizontal  synchronization  signal 

STRLONG 

03E 

D 

s 

d 

Long  horizontal  line  marker 
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The  following  registers  can  be  accessed  by  Copper  when  COPCON  =  1. 


Name 

Reg.addr. 

Chip 

R/W 

p/d 

Function 

BLTCONO 

040 

A 

w 

P 

Blitter  control  register  0 

BLTCON1 

042 

A 

w 

P 

Blitter  control  register  1 

BLTAFWM 

044 

A 

w 

P 

Mask  for  first  data  word  from  A 

BLTALWM 

046 

A 

w 

P 

Mask  for  last  data  word  from  A 

BLTCPTH 

048 

A 

w 

P 

Address  of  source  data  C  bits  16-20 

BLTCPTL 

04A 

A 

w 

P 

Address  of  source  data  C  bits  1-15 

BLTBPTH 

04C 

A 

w 

P 

Address  of  source  data  B  bits  16-20 

BLTBPTL 

04E 

A 

w 

P 

Address  of  source  data  B  bits  1-15 

BLTAPTH 

050 

A 

w 

P 

Address  of  source  data  A  bits  16-20 

BLTAPTL 

052 

A 

w 

P 

Address  of  source  data  A  bits  1-15 

BLTDPTH 

054 

A 

w 

P 

Address  of  destination  data  D  bits  1 6-20 

BLTDPTL 

056 

A 

w 

P 

Address  of  destination  data  D  bits  1-15 

BLTSIZE 

058 

A 

w 

P 

Start  bit  and  size  of  Blitter  window 

BLTCONOL 

05A 

A 

w 

P 

Like  BLTCONO,  bits  0-7 

BLTSIZEV 

05C 

A 

w 

P 

Width  of  Blitter  window 

BLTSIZEH 

05E 

A 

w 

P 

Height  of  Blitter  window 

BLTCMOD 

060 

A 

w 

P 

Blitter  modulo  for  source  data  C 

BLTBMOD 

062 

A 

w 

P 

Blitter  modulo  for  source  data  B 

BLTAMOD 

064 

A 

w 

P 

Blitter  modulo  for  source  data  A 

BLTDMOD 

066 

A 

w 

P 

Blitter  modulo  for  destination  data  D 

— 

068 

Unused 

— 

06A 

Unused 

— 

06C 

Unused 

— 

06E 

Unused 

BLTCDAT 

070 

A 

w 

d 

Blitter  source  data  register  C 

BLTBDAT 

072 

A 

w 

d 

Blitter  source  data  register  B 

BLTADAT 

074 

A 

w 

d 

Blitter  source  data  register  A 

— 

076 

Unused 

— 

078 

Unused 

— 

07A 

Unused 

DENISEID 

07C 

D 

r 

P 

Chip  identification  from  Denise 

DSKSYNC 

07E 

P 

w 

P 

Disk  sync  pattern 

The  following  registers  can  always  be  written  by  the  Copper. 


Name 

Reg.addr. 

Chip 

R/W 

p/d 

Function 

COP1LCH 

080 

A 

w 

P 

Address  of  1st  Copper  list  bits  16-20 

COP1LCL 

082 

A 

w 

P 

Address  of  1st  Copper  list  bits  1-15 

COP2LCH 

084 

A 

w 

P 

Address  of  2nd  Copper  list  bits  16-20 

COP2LCL 

086 

A 

w 

P 

Address  of  2nd  Copper  list  bits  1-15 

COPJMP1 

088 

A 

s 

P 

Jump  to  start  of  1st  Copper  list 

COPJMP2 

08A 

A 

s 

P 

Jump  to  start  of  2nd  Copper  list 

COPINS 

08C 

A 

w 

d 

Copper  command  register 

DIWSTRT 

08E 

A 

w 

P 

Upper  left  corner  of  display  window 

DIWSTOP 

090 

A 

w 

P 

Lower  right  corner  of  display  window 

DDFSTRT 

092 

A 

w 

P 

Start  of  bit-plane  DMA  (horiz.  pos.) 

DDFSTOP 

094 

A 

w 

P 

End  of  bit-plane  DMA  (horiz.  pos.) 
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Name 

Reg.addr. 

Chip 

R/W 

p/d 

Function 

DMACON 

096 

ADP 

w 

p 

Write  DMA  control  register 

CLXCON 

098 

D 

w 

p 

Write  collision  control  register 

INTENA 

09A 

P 

w 

p 

Write  interrupt  enable 

INTREQ 

09C 

P 

w 

p 

Write  interrupt  request 

ADKCON 

09E 

P 

w 

p 

Audio,  disk  and  UART  control  register 

AUDOLCH 

0A0 

A 

w 

p 

Address  of  audio  data  bits  16-20 

AUDOLCL 

0A2 

A 

w 

p 

On  sound  channel  0,  bits  1-15 

AUDOLEN 

0A4 

P 

w 

p 

Channel  0  length  of  audio  data 

AUDOPER 

0A6 

P 

w 

p 

Channel  0  period  duration 

AUDOVOL 

0A8 

P 

w 

p 

Channel  0  volume 

AUDODAT 

OAA 

P 

w 

d 

Channel  0  audio  data  (to  D/A  converter) 

— 

OAC 

Unused 

— 

OAE 

Unused 

AUD1LCH 

0B0 

A 

w 

p 

Address  of  audio  data  bits  16-20 

AUD1LCL 

0B2 

A 

w 

p 

On  sound  channel  1,  bits  1-15 

AUD1LEN 

0B4 

P 

w 

p 

Channel  1  length  of  audio  data 

AUDI PER 

0B6 

P 

w 

p 

Channel  1  period  duration 

AUDI VOL 

0B8 

P 

w 

p 

Channel  1  volume 

AUDI DAT 

OBA 

P 

w 

d 

Channel  1  audio  data  (to  D/A  converter) 

— 

OBC 

Unused 

— 

OBE 

Unused 

AUD2LCH 

OCO 

A 

w 

p 

Address  of  audio  data  bits  16-20 

AUD2LCL 

0C2 

A 

w 

p 

On  sound  channel  2,  bits  1-15 

AUD2LEN 

0C4 

P 

w 

p 

Channel  2  length  of  audio  data 

AUD2PER 

0C6 

P 

w 

p 

Channel  2  period  duration 

AUD2VOL 

0C8 

P 

w 

p 

Channel  2  volume 

AUD2DAT 

OCA 

P 

w 

d 

Channel  2  audio  data  (to  D/A  converter) 

— 

OCC 

Unused 

— 

OCE 

Unused 

AUD3LCH 

ODO 

A 

w 

P 

Address  of  audio  data  bits  1 6-20 

AUD3LCL 

0D2 

A 

w 

P 

On  sound  channel  3,  bits  1-15 

AUD3LEN 

0D4 

P 

w 

P 

Channel  3  length  of  audio  data 

AUD3PER 

0D6 

P 

w 

P 

Channel  3  period  duration 

AUD3VOL 

0D8 

P 

w 

p 

Channel  3  volume 

AUD3DAT 

ODA 

P 

w 

d 

Channel  3  audio  data  (to  D/A  converter) 

— 

ODC 

Unused 

— 

ODE 

Unused 

BPL1PTH 

OEO 

A 

w 

P 

Address  of  bit-plane  1,  bits  16-20 

BPL1PTL 

0E2 

A 

w 

P 

Address  of  bit-plane  1 ,  bits  1-15 

BPL2PTH 

0E4 

A 

w 

P 

Address  of  bit-plane  2,  bits  16-20 

BPL2PTL 

0E6 

A 

w 

P 

Address  of  bit-plane  2,  bits  1-15 

BPL3PTH 

0E8 

A 

w 

P 

Address  of  bit-plane  3,  bits  16-20 

BPL3PTL 

OEA 

A 

w 

P 

Address  of  bit-plane  3,  bits  1-15 

BPL4PTH 

OEC 

A 

w 

P 

Address  of  bit-plane  4,  bits  16-20 

BPL4PTL 

OEE 

A 

w 

P 

Address  of  bit-plane  4,  bits  1-15 

BPL5PTH 

OFO 

A 

w 

P 

Address  of  bit-plane  5,  bits  16-20 

BPL5PTL 

0F2 

A 

w 

P 

Address  of  bit-plane  5,  bits  1-15 

BPL6PTH 

0F4 

A 

w 

P 

Address  of  bit-plane  6,  bits  16-20 

BPL6PTL 

0F6 

A 

w 

P 

Address  of  bit-plane  6,  bits  1-15 

— 

0F8 

Unused 
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Name 


Reg.addr. 


Chip 


R/W       p/d       Function 


— 

OFA 

— 

OFC 

— 

OFE 

BPLCONO 

100 

AD 

w 

p 

BPLCON1 

102 

D 

w 

p 

BPLCON2 

104 

D 

w 

p 

BPLCON3 

106 

D 

w 

p 

BPL1MOD 

108 

A 

w 

p 

BPL2MOD 

10A 

A 

w 

p 

— 

10C 

— 

10E 

BPL1DAT 

110 

D 

w 

d 

BPL2DAT 

112 

D 

w 

d 

BPL3DAT 

114 

D 

w 

d 

BPL4DAT 

116 

D 

w 

d 

BPL5DAT 

118 

D 

w 

d 

BPL6DAT 

11A 

D 

w 

d 

— 

11C 

— 

11E 

SPROPTH 

120 

A 

w 

P 

SPROPTL 

122 

A 

w 

P 

SPR1PTH 

124 

A 

w 

P 

SPR1PTL 

126 

A 

w 

P 

SPR2PTH 

128 

A 

w 

P 

SPR2PTL 

12A 

A 

w 

P 

SPR3PTH 

12C 

A 

w 

P 

SPR3PTL 

12E 

A 

w 

P 

SPR4PTH 

130 

A 

w 

P 

SPR4PTL 

132 

A 

w 

P 

SPR5PTH 

134 

A 

w 

P 

SPR5PTL 

136 

A 

w 

P 

SPR6PTH 

138 

A 

w 

P 

SPR6PTL 

13A 

A 

w 

P 

SPR7PTH 

13C 

A 

w 

P 

SPR7PTL 

13E 

A 

w 

P 

SPROPOS 

140 

AD 

w 

dp 

SPROCTL 

142 

AD 

w 

dp 

SPRODATA 

144 

D 

w 

dp 

SPRODATB 

146 

D 

w 

dp 

SPR1POS 

148 

AD 

w 

dp 

SPR1CTL 

14A 

AD 

w 

dp 

SPR1DATA 

14C 

D 

w 

dp 

SPR1DATB 

14E 

D 

w 

dp 

SPR2POS 

150 

AD 

w 

dp 

SPR2CTL 

152 

AD 

w 

dp 

SPR2DATA 

154 

D 

w 

dp 

SPR2DATB 

156 

D 

w 

dp 

SPR3POS 

158 

AD 

w 

dp 

SPR3CTL 

15A 

AD 

w 

dp 

SPR3DATA 

15C 

D 

w 

dp 

Unused 

Unused 

Unused 

Bit-plane  control  register  0 

Control  register  1  (scroll  values) 

Control  register  2  (priority  control) 

Control  register  3 

Bit-plane  modulo  for  uneven  planes 

Bit-plane  modulo  for  even  planes 

Unused 

Unused 

Bit-plane  1  data  (to  RGB  output) 

Bit-plane  2  data  (to  RGB  output) 

Bit-plane  3  data  (to  RGB  output) 

Bit-plane  4  data  (to  RGB  output) 

Bit-plane  5  data  (to  RGB  output) 

Bit-plane  6  data  (to  RGB  output) 

Unused 

Unused 

Sprite  data  0,  bits  16-18 

Sprite  data  0,  bits  1-15 

Sprite  data  1 ,  bits  16-18 

Sprite  data  1,  bits  1-15 

Sprite  data  2,  bits  16-18 

Sprite  data  2,  bits  1-15 

Sprite  data  3,  bits  16-18 

Sprite  data  3,  bits  1-15 

Sprite  data  4,  bits  16-18 

Sprite  data  4,  bits  1-15 

Sprite  data  5,  bits  16-18 

Sprite  data  5,  bits  1-15 

Sprite  data  6,  bits  16-18 

Sprite  data  6,  bits  1-15 

Sprite  data  7,  bits  16-18 

Sprite  data  7,  bits  1-15 

Sprite  0  start  position  (vert,  and  horiz.) 

Sprite  0  control  reg.  and  vertical  stop 

Sprite  0  data  register  A  (to  RGB  output) 

Sprite  0  data  register  B  (to  RGB  output) 

Sprite  1  start  position  (vert,  and  horiz.) 

Sprite  1  control  reg.  and  vertical  stop 

Sprite  1  data  register  A  (to  RGB  output) 

Sprite  1  data  register  B  (to  RGB  output) 

Sprite  2  start  position  (vert,  and  horiz.) 

Sprite  2  control  reg.  and  vertical  stop 

Sprite  2  data  register  A  (to  RGB  output) 

Sprite  2  data  register  B  (to  RGB  output) 

Sprite  3  start  position  (vert,  and  horiz.) 

Sprite  3  control  reg.  and  vertical  stop 

Sprite  3  data  register  A  (to  RGB  output) 
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Name 

Reg.addr. 

Chip 

R/W 

p/d 

Function 

SPR3DATB 

15E 

D 

w 

dp 

Sprite  3  data  register  B  (to  RGB  output) 

SPR4P0S 

160 

AD 

w 

dp 

Sprite  4  start  position  (vert,  and  horiz.) 

SPR4CTL 

162 

AD 

w 

dp 

Sprite  4  control  reg.  and  vertical  stop 

SPR4DATA 

164 

D 

w 

dp 

Sprite  4  data  register  A  (to  RGB  output) 

SPR4DATB 

166 

D 

w 

dp 

Sprite  4  data  register  B  (to  RGB  output) 

SPR5P0S 

168 

AD 

w 

dp 

Sprite  5  start  position  (vert,  and  horiz.) 

SPR5CTL 

16A 

AD 

w 

dp 

Sprite  5  control  reg.  and  vertical  stop 

SPR5DATA 

16C 

D 

w 

dp 

Sprite  5  data  register  A  (to  RGB  output) 

SPR5DATB 

16E 

D 

w 

dp 

Sprite  5  data  register  B  (to  RGB  output) 

SPR6P0S 

170 

AD 

w 

dp 

Sprite  6  start  position  (vert,  and  horiz.) 

SPR6CTL 

172 

AD 

w 

dp 

Sprite  6  control  reg.  and  vertical  stop 

SPR6DATA 

174 

D 

w 

dp 

Sprite  6  data  register  A  (z.  RGB  output.) 

SPR6DATB 

176 

D 

w 

dp 

Sprite  6  data  register  B  (to  RGB  output) 

SPR7P0S 

178 

AD 

w 

dp 

Sprite  7  start  position  (vert,  and  horiz.) 

SPR7CTL 

17A 

AD 

w 

dp 

Sprite  7  control  reg.  and  vertical  stop 

SPR7DATA 

17C 

D 

w 

dp 

Sprite  7  data  register  A  (to  RGB  output) 

SPR7DATB 

17E 

D 

w 

dp 

Sprite  7  data  register  B  (to  RGB  output) 

COLOROO 

180 

D 

w 

p 

Color  palette  register  0  (color  table) 

COLOR01 

182 

D 

w 

p 

Color  palette  register  1  (color  table) 

COLOR02 

184 

D 

w 

p 

Color  palette  register  2  (color  table) 

COLOR03 

186 

D 

w 

p 

Color  palette  register  3  (color  table) 

COLOR04 

188 

D 

w 

p 

Color  palette  register  4  (color  table) 

COLOR05 

18A 

D 

w 

p 

Color  palette  register  5  (color  table) 

COLOR06 

18C 

D 

w 

p 

Color  palette  register  6  (color  table) 

COLOR07 

18E 

D 

w 

p 

Color  palette  register  7  (color  table) 

COLOR08 

190 

D 

w 

p 

Color  palette  register  8  (color  table) 

COLOR09 

192 

D 

w 

p 

Color  palette  register  9  (color  table) 

COLOR10 

194 

D 

w 

p 

Color  palette  register  10  (color  table) 

COLOR11 

196 

D 

w 

p 

Color  palette  register  1 1  (color  table) 

COLOR12 

198 

D 

w 

p 

Color  palette  register  12  (color  table) 

COLOR13 

19A 

D 

w 

p 

Color  palette  register  13  (color  table) 

COLOR14 

19C 

D 

w 

p 

Color  palette  register  14  (color  table) 

COLOR15 

19E 

D 

w 

p 

Color  palette  register  15  (color  table) 

COLOR  16 

1A0 

D 

w 

p 

Color  palette  register  16  (color  table) 

COLOR  17 

1A2 

D 

w 

p 

Color  palette  register  17  (color  table) 

COLOR  18 

1A4 

D 

w 

p 

Color  palette  register  18  (color  table) 

COLOR19 

1A6 

D 

w 

p 

Color  palette  register  19  (color  table) 

COLOR20 

1A8 

D 

w 

p 

Color  palette  register  20  (color  table) 

COLOR21 

1AA 

D 

w 

p 

Color  palette  register  21  (color  table) 

COLOR22 

1AC 

D 

w 

p 

Color  palette  register  22  (color  table) 

COLOR23 

1AE 

D 

w 

p 

Color  palette  register  23  (color  table) 

COLOR24 

1B0 

D 

w 

p 

Color  palette  register  24  (color  table) 

COLOR25 

1B2 

D 

w 

p 

Color  palette  register  25  (color  table) 

COLOR26 

1B4 

D 

w 

p 

Color  palette  register  26  (color  table) 

COLOR27 

1B6 

D 

w 

p 

Color  palette  register  27  (color  table) 

COLOR28 

1B8 

D 

w 

p 

Color  palette  register  28  (color  table) 

COLOR29 

1BA 

D 

w 

p 

Color  palette  register  29  (color  table) 

COLOR30 

1BC 

D 

w 

p 

Color  palette  register  30  (color  table) 

COLOR31 

1BE 

D 

w 

p 

Color  palette  register  31  (color  table) 

HTOTAL 

1C0 

A 

w 

p 

Clock  count  per  line  (VARBEAM=1) 
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Name 


Reg.addr.      Chip      R/W       p/d       Function 


HSSTOP 

1C2 

A 

w 

p 

H-sync  stop  position 

HBSTRT 

1C4 

A 

w 

p 

H-blank  start  position 

HBSTOP 

1C6 

A 

w 

p 

H-blank  stop  position 

VTOTAL 

1C8 

A 

w 

p 

Number  of  lines  per  picture 

VSSTOP 

1CA 

A 

w 

p 

V-sync  stop  line 

VBSTRT 

1CC 

A 

w 

p 

V-blank  start  line 

VBSTOP 

1CE 

A 

w 

p 

V-blank  stop  line 

SPRHSTRT 

1D0 

A 

w 

p 

UHRES  sprite  start  line 

SPRHSTOP 

1D2 

A 

w 

p 

UHRES  sprite  stop  line 

BPLHSTRT 

1D4 

A 

w 

p 

UHRES  bit-plane  start  line 

BPLHSTOP 

1D6 

A 

w 

p 

UHRES  bit-plane  stop  line 

HHPOSW 

1D8 

A 

w 

p 

Write  DUAL-mode  column  counter 

HHPOSR 

1DA 

A 

r 

p 

Read  DUAL-mode  column  counter 

BEAMCONO 

1DC 

A 

w 

p 

Raster  beam  control  register 

HSSTRT 

1DE 

A 

w 

p 

H-sync  start  position 

VSSTRT 

1E0 

A 

w 

p 

V-sync  start  position 

HCENTER 

1E2 

A 

w 

p 

H-pos.  of  V-sync  in  interlace  mode 

DIWHIGH 

1E4 

A,D 

w 

p 

Screen  window,  upper  bits  for  start/stop 

BPLHMOD 

1E6 

A 

w 

p 

UHRES  bit-plane  modulo 

SPRHPTH 

1E8 

A 

w 

p 

UHRES  sprite  pointer  (bits  16-20) 

SPRHPTL 

1EA 

A 

w 

p 

UHRES  sprite  pointer  (bits  0-15) 

BPLHPTH 

1EC 

A 

w 

p 

UHRES  bit-plane  pointer  (bits  16-20) 

BPLHPTL 

1EE 

A 

w 

p 

UHRES  bit-plane  pointer  (bits  0-15) 
The  registers  1 F0  to  1 FC  are  unoccupied 

ROM 

The  figure  on  page  771  shows  the  ROM  area  as  it  appears  after  booting. 
The  512K  of  ROM  at  $00F80000  contains  the  Amiga  Kickstart.  This 
configuration  can  change.  After  a  reset,  the  68030  fetches  the  address  of 
the  first  instruction  from  memory  location  4,  called  the  reset  vector.  If  the 
memory  configuration  could  not  be  changed,  the  68000  would  fetch  the 
reset  vector  from  chip  RAM,  which  is  at  address  4.  Since  the  contents  of 
this  location  are  undefined  at  start-up,  the  processor  would  jump  to  some 
random  address  and  the  system  would  crash.  The  solution  to  this  is  as 
follows:  The  chip  that  is  responsible  for  the  memory  configuration  has  an 
input  that  is  connected  to  the  lowest  port  line  of  CIA-A  (PA0).  This  OVL 
(Memory  Overlay)  line  is  normally  at  0,  and  the  memory  configuration 
corresponds  to  the  figure.  After  a  reset,  the  port  line  automatically  goes 
high,  causing  the  ROM  area  at  $00F80000  to  $00FFFFFF  to  be  mapped 
into  the  range  from  0  to  $7FFFF.  This  means  that  address  4  (the  reset 
vector)  then  corresponds  to  address  $F80004.  Here  the  68030  finds  a 
valid  reset  address,  which  tells  it  to  jump  to  the  Kickstart  program.  In  the 
course  of  the  reset  routine  the  OVL  line  is  set  to  0  and  the  normal 
memory  configuration  returns. 
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You  must  be  very  careful  when  experimenting  with  this  line.  If  the 
program  that  tries  to  set  the  OVL  line  is  running  in  chip  RAM,  the  result 
can  be  catastrophic,  because  the  program  more  or  less  switches  itself  out 
of  the  memory  range  and  the  processor  lands  somewhere  in  the  Kickstart, 
which  takes  the  place  of  the  chip  RAM  after  the  switch. 

Since  the  final  version  of  the  operating  system  was  not  yet  ready  when 
the  first  A3000's  were  manufactured,  the  Kickstart  had  to  be  booted  from 
the  hard  disk.  In  place  of  the  Kickstart,  a  boot  program  was  placed  in 
ROM.  After  the  Kickstart  was  loaded  to  fast  RAM,  it  would  be 
transferred  to  $0OF800O0  with  the  68030's  PMMU. 


11.7.2        Fundamentals 


As  mentioned  in  the  previous  section,  there  are  some  registers  that  are 
accessed  by  the  processor  and  some  that  are  read  and  written  via  DMA. 
We'll  begin  by  discussing  the  former. 

Programming  the  chip  registers 

The  chip  registers  can  be  addressed  directly  (e.g.,  changing  the  value  of 
the  background  color  register).  The  register  has  the  name  COLOR00. 
Looking  in  the  register  table,  you  see  that  it  has  a  register  address  of 
$180. 

So,  we  must  add  the  base  address  of  the  register  area  (i.e.,  the  address  of 
the  first  register  in  the  address  range  that  the  68030  accesses).  This  is 
$DFF000.  Also,  the  register  address  of  COLOROO  yields  $DFF180.  A 
simple  MOVE.W  command  can  be  used  to  initialize  the  register: 


MOVE.W  #value,$DFF180      /value  in  COLOROO 


If  more  than  one  register  is  accessed,  it  is  a  good  idea  to  store  the  base 
address  in  an  address  register  and  use  indirect  addressing  with  an  offset. 
Here  is  an  example: 


LEA    $DFF000,A5  ; store  base  address  in  A5 

MOVE.W  #valuel,$180(A5)  ;valuel  in  COLOROO 

MOVE.W  #value2,$182(A5)  ;value2  in  COLOR01 
MOVE.W  .. .  etc. 


780 


11.7  Programming  the  Hardware 


Normally  the  chip  registers  are  accessed  as  previously  shown.  However, 
the  registers  can  also  be  accessed  as  a  long  word.  In  this  case  two 
registers  are  always  written  at  once.  This  makes  sense  for  the  address 
registers,  which  consist  of  a  pair  of  registers  holding  a  single  21 -bit 
address,  with  which  the  entire  2048K  chip  RAM  area  can  be  accessed. 
All  data  for  the  custom  chips  must  be  in  the  chip  RAM.  Since  the  chips 
always  address  the  memory  word-wise,  the  lowest  bit  (bit  0)  is  irrelevant. 
The  address  register  points  only  to  even  addresses.  Since  a  chip  register 
is  only  one  word  (16  bits)  wide,  two  successive  registers  are  used  to  store 
the  21-bit  memory  address.  The  first  register  contains  the  upper  5  bits 
(bits  16-20)  and  the  second  contains  the  lower  16  (bits  0-15).  This  makes 
it  possible  to  initialize  both  registers  with  a  single  long-word  access. 
Example:  Setting  the  pointer  for  the  first  bit-plane  to  address  $40000. 
BPL1PTH  is  the  name  of  the  first  register  (bits  16-20)  and  BPL1PTL  (bits 
0-15)  is  the  name  of  the  second.  Register  address  of  BPL1PTH:  $0E0, 
BPL1PTL  =  $0E2. 

A5  contains  the  base  address  $DFF000. 

MOVE.L  #$40000, $0E0(A5)     ; initializes  BPL1PTH  and  BPL1PTL  with  the  correct  values. 

Any  given  register  address  can  never  be  both  read  from  and  written  to. 
Most  registers  are  write-only  registers  and  cannot  be  read.  This  also 
includes  the  registers  previously  mentioned.  Others  can  only  be  read. 
Only  a  few  can  be  read  and  written,  but  these  have  two  different  register 
addresses,  one  for  reading  and  one  for  writing.  The  DMA  control  register, 
which  will  be  discussed  in  detail  later,  is  such  a  register.  It  can  be  written 
through  the  register  address  $096  (DMACON),  while  address  $002  is 
used  for  reading  (DMACONR). 

DMA  access 

DMA  involves  the  direct  access  of  a  special  component,  called  the  DMA 
controller,  to  the  system  memory.  In  the  case  of  the  Amiga,  the  DMA 
controller  is  housed  in  Agnus.  It  represents  the  connection  between  the 
various  input/output  components  of  the  custom  chips  and  the  chip 
RAM.  The  DMA  process  follows  the  same  pattern  regardless  of  whether 
diskette,  screen  or  audio  data  is  involved.  A  given  I/O  component,  such 
as  the  disk  controller,  needs  new  data  or  has  data  that  it  wants  to  store  in 
memory.  The  DMA  controller  waits  until  the  memory  for  this  channel  is 
free  (not  being  accessed  by  another  DMA  channel  or  the  processor)  and 
then  transfers  the  data  to  or  from  RAM  itself.  For  the  sake  of  simplicity 
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there  is  no  special  transfer  of  the  data  from  the  I/O  device  to  the  DMA 
controller.  It  always  takes  place  through  registers.  Each  of  these  I/O 
components  has  two  different  types  of  registers.  One  type  is  the  normal 
registers  which  are  accessed  by  the  processor  and  in  which  the  various 
operating  parameters  are  stored.  The  second  is  the  data  registers  that 
contain  the  data  for  the  DMA  controller.  For  a  DMA  transfer  this 
involves  simply  the  corresponding  data  register  and  a  RAM  location. 
Depending  on  the  direction  of  the  transfer,  either  a  read  register  is 
selected  and  the  chip  RAM  is  set  for  write,  or  a  write  register  is  used  and 
the  chip  RAM  is  set  for  read.  Since  the  two  can  be  connected  through 
the  data  bus,  the  data  are  automatically  routed  to  their  destination.  Data 
are  not  stored  in  any  temporary  registers. 

The  DMA  transfer  adds  a  third  type  of  register:  the  DMA  address  register 
which  holds  the  address  or  addresses  of  the  data  in  RAM,  depending  on 
the  needs  of  the  I/O  device. 

There  are  many  central  control  registers  that  are  not  assigned  to  a  special 
I/O  device,  but  have  higher-level  control  functions.  The  DMACON 
register  belongs  in  this  category. 

The  data  registers  can  also  be  written  by  the  processor,  since  they  are 
realized  in  the  form  of  normal  registers.  However,  this  is  not  generally 
useful,  since  the  DMA  controller  can  accomplish  this  more  quickly  and 
efficiently. 

Some  I/O  components  do  not  have  DMA  channels.  The  68030  must  read 
and  write  their  data  itself.  This  group  includes  only  those  devices  which 
by  their  nature  do  not  deal  with  large  quantities  of  data,  so  that  DMA  is 
not  needed,  such  as  the  joystick  and  mouse  inputs. 

The  following  DMA  channels  are  present: 

Bit-plane  DMA  Through  this  DMA  channel  the  screen  data  are  read 
from  memory  and  written  into  the  data  registers  of  the 
individual  bit-planes.  From  there  they  go  to  the  bit- 
plane  sequencers,  which  convert  the  data  for  output  to 
the  screen. 

Sprite  DMA  Transfers  the  sprite  data  from  the  RAM  to  the  sprite 
data  registers. 
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Disk  DMA 


Transfers  data  from  disk  to  RAM  or  from  RAM  to  disk. 


Audio  DMA        Reads  digital  sound  data  from  RAM  and  writes  it  to  the 
appropriate  audio  data  registers. 

Copper  DMA     The  coprocessor  (Copper)  receives  its  command  words 
through  this  channel. 

Blitter  DMA       Transfers  data  from  and  to  the  Blitter. 

There  are  a  total  of  six  DMA  channels  which  all  want  to  access  the 
memory,  and  the  processor,  which  naturally  also  wants  to  have  the  chip 
RAM  for  itself  as  often  as  possible.  To  solve  the  problems  that  result  from 
this,  a  complex  system  of  time  multiplexing  was  devised  in  which  the 
individual  channels  have  defined  positions.  Since  this  is  oriented  to  the 
video  picture,  first  we  must  briefly  discuss  its  construction.  This  section 
has  been  kept  as  simple  as  possible,  since  we  are  discussing  the 
programming  of  the  custom  chips  and  not  the  hardware. 
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Construction  of  the  video  picture 


First  half 
screen's 
lines  (all 
odd-numbered 
lines  are  in 
long  frame) 


Complete  screen 


Second  half 

screen's 

lines  (all 

even-numbered 

lines  are  in 

short  frame) 


Construction  of  the  picture 

The  timing  of  the  Amiga  screen  output  corresponds  exactly  to  the 
standard  of  the  country  where  the  Amiga  is  sold,  PAL  for  Europe  and 
NTSC  for  the  US.  The  8361  Agnus  chip  is  available  in  an  NTSC  US 
version  and  a  PAL  version  for  Europe.  A  PAL  video  picture  consists  of 
625  horizontal  lines,  an  NTSC  picture  of  525  horizontal  lines.  Each  of 
these  lines  is  constructed  from  left  to  right.  A  pause  follows  every  line, 
called  the  horizontal  blanking  gap,  in  which  the  electron  beam  that 
draws  the  picture  has  time  to  go  back  from  right  to  left.  During  this 
blanking  gap  the  electron  beam  is  dark  so  that  it  cannot  be  seen  tracing 
back  to  the  left  side.  Then  the  process  starts  over  again  and  the  next  line 
appears. 
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To  keep  the  picture  free  of  flickering,  it  must  be  continually  redrawn. 
Since  our  eyes  cannot  discern  changes  above  a  certain  frequency,  the 
number  of  pictures  per  second  is  placed  above  this  limit.  With  the  PAL 
standard,  the  number  of  individual  pictures  is  set  to  50  per  second  (30 
per  second  for  NTSC).  But  now  we  encounter  a  problem.  If  all  625  lines 
were  drawn  50  times  per  second,  the  result  would  be  31250  lines  per 
second.  If  monitors  and  televisions  were  built  to  these  specifications, 
they  would  not  be  affordably  priced,  so  a  trick  is  used.  On  one  hand,  the 
number  of  pictures  should  not  be  less  than  50  per  second  or  the  screen 
begins  to  flicker,  while  on  the  other  hand  there  must  be  enough  lines  per 
picture.  The  solution  is  as  follows:  50  pictures  are  displayed  per  second, 
but  the  625  lines  are  divided  into  two  pictures.  The  first  picture  contains 
all  the  odd  lines  (1,3,5...625),  while  the  second  contains  all  the  even  lines 
(2,4,6...624).  Two  of  these  half-pictures  (called  frames)  are  combined  to 
form  the  entire  picture,  which  contains  625  lines.  Naturally,  the  number 
of  complete  pictures  per  second  is  only  half  as  large  as  the  number  of 
half-pictures,  or  25  per  second.  The  line  frequency  for  this  technique  is 
only  15625  Hz  (25x625  or  50x312.5). 

In  spite  of  the  high  resolution  of  625  lines,  flickering  occurs  when  a 
contour  is  restricted  to  only  one  line.  Then  it  is  displayed  only  every  25th 
of  a  second,  which  is  perceived  by  the  eye  as  a  visible  flickering.  This 
effect  can  be  seen  on  televisions  (especially  on  the  horizontal  edges  of 
surfaces),  since  these  consist  of  only  a  single  horizontal  line. 

The  term  for  this  technique  of  alternating  display  of  even  and  odd  lines  is 
interlacing.  Two  additional  terms  are  used  to  distinguish  the  difference 
between  the  two  types  of  half -pictures.  A  long  frame  is  the  one  in  which 
the  odd  lines  are  displayed,  and  the  other  is  called  a  short  frame.  They  are 
called  long  and  short  frames  because  there  is  one  more  odd  line  than 
even  and  it  takes  slighdy  longer  to  display  the  frame  containing  the  extra 
line  (from  1  to  625  there  are  313  odd  and  312  even  numbers). 

After  each  frame  there  is  a  pause  before  the  next  frame  begins.  This  blank 
space  between  frames  is  called  the  vertical  blanking  gap.  The  picture 
created  by  the  Amiga  also  follows  this  scheme,  although  with  some 
deviations. 

Normally  the  second  half-picture  (short  frame)  is  somewhat  delayed  so 
that  the  even  lines  appear  exactly  between  the  odd  lines. 
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On  the  Amiga  both  frames  are  identical  so  that  the  frequency  is  actually 
50  Hz.  As  a  result,  the  number  of  lines  is  limited  to  313.  This  can  be 
clearly  seen  by  the  vertical  distance  between  two  lines  on  the  screen, 
since  the  frames  are  no  longer  displaced,  but  drawn  on  top  of  each  other. 

To  increase  the  number  of  lines,  the  Amiga  can  also  create  its  picture  in 
interlace  mode.  Then  a  full  625  lines  are  possible  on  PAL  systems,  but  the 
disadvantages  of  interlace  operation  must  be  considered.  More  about 
this  later. 

Construction  of  the  Amiga  screen  output 

Bit-planes 

The  Amiga  always  displays  its  picture  in  a  type  of  graphic  mode  (i.e., 
each  point  on  the  screen  has  a  corresponding  representation  in  memory). 

The  simplest  way  to  build  a  screen  image  in  memory  is  to  define  a 
contiguous  block  of  RAM  in  which  a  set  bit  corresponds  to  a  point 
(pixel)  displayed  on  the  monitor.  This  basic  construction  is  called  a 
bit-plane  and  is  the  fundamental  element  of  all  screen  display  in  the 
Amiga.  A  single  line  on  the  screen  will  consist  of  a  certain  number  of 
words  determined  by  the  width  of  the  picture.  Since  each  bit  represents 
one  pixel,  a  word  comprises  16  pixels.  For  a  screen  display  of  320  pixels 
per  line,  20  (320/16)  words  per  line  are  needed. 

In  a  single  bit-plane,  only  one  of  two  possible  conditions  can  exist  for  a 
given  bit  position.  The  bit  is  either  set  or  cleared.  However,  by  combining 
several  bit-planes,  the  possibilities  are  greatly  expanded.  The  planes  can 
be  logically  superimposed  so  that  those  bits  having  the  same  position 
within  their  respective  planes  are  considered  as  a  unit.  The  first  pixel  on 
the  screen  is  the  result  of  combining  the  first  bit  of  the  first  word  of  all  the 
bit-planes.  The  value  of  the  bit  combination  determines  the  color  of  the 
pixel  on  the  screen.  There  are  various  ways  of  deriving  colors  from  bit 
combinations,  and  we'll  discuss  these  in  more  detail  later. 
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Bit-plane  structure  :  320x200  pixels  :  restarting  address 

Column     o                            16                           32                •  •  •           304 

Row            n  +  O                       n  +  2                       n  +  4                               n  +  38 

0 

1st  word 

|     2nd  word 
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...| 
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•  a                                      • 

•  •                                      • 

•  •                                      • 
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TT T i  i  1 r 1  1  1  1  i  i  i  i  j 

Representation  of  bit-plane's  first  word  in  the  upper-left 
corner  of  the  visible  screen 

Bit-plane  construction 

Different  graphic  resolutions 

The  Amiga  recognizes  three  different  horizontal  resolutions.  The  high 
resolution  mode  normally  has  640  pixels  per  line,  the  low  resolution  has 
320.  The  A3000's  new  Denise  even  permits  a  1280  pixel-per-line  display 
called  super  hi-res  mode.  The  word  "normally"  means  that  this  value  can 
change.  It  is  better  to  define  the  different  resolutions  in  terms  of  time  per 
pixel.  A  pixel  in  super  hi-res  mode  is  displayed  for  35  nanoseconds,  in 
normal  hi-res  mode  for  70  nanoseconds  and  in  low-resolution  mode  for 
140  nanoseconds.  Comparing  lo-res  to  hi-res,  the  electron  beam  traces 
across  the  screen  for  twice  the  time  to  produce  a  single  pixel.  In  this  time 
it  covers  twice  the  distance,  producing  a  pixel  that  appears  twice  as  wide 
in  low  as  in  high  resolution. 

What  is  more  important  for  the  programmer  to  know,  however,  is  that  in 
high-resolution  mode  only  four  bit-planes  can  be  active  at  a  time,  while  in 
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low-resolution  mode  up  to  six  planes  are  allowed.  In  super  hi-res  mode 
only  two  bit-planes  may  be  used.  Furthermore,  a  limitation  of  64  colors  is 
imposed  on  the  color  palette.  This  is  a  consequence  not  of  higher  pixel 
frequency,  but  of  certain  limitations  in  the  chip  design. 

Construction  of  a  horizontal  raster  line 

A  raster  line  is  a  complete  horizontal  line,  including  both  the  horizontal 
blanking  gap  and  the  visible  region.  This  raster  line  serves  as  a  timing 
measure  for  all  DMA  processes,  particularly  for  screen-associated  DMAs. 
To  understand  the  division  of  the  raster  line,  you  must  know  how 
memory  access  to  chip  RAM  and  the  custom  chip  registers  is  distributed 
between  the  DMA  controller  and  the  processor.  Accesses  to  these  two 
storage  areas  must  conform  to  what  are  called  bus  cycles.  The  bus  cycles 
determine  the  timing  of  the  chip  RAM.  One  memory  access  can  take 
place  in  each  bus  cycle.  It  doesn't  matter  whether  the  data  is  read  or 
written. 

For  example,  if  the  processor  wants  to  access  the  bus  it  gets  control  of 
the  bus  for  one  bus  cycle.  The  DMA  controller  cannot  access  RAM 
again  until  the  following  cycle.  A  bus  cycle  lasts  280  nanoseconds. 
Almost  four  memory  accesses  are  possible  in  one  microsecond. 

For  compatibility  reasons,  processor  accesses  to  chip  memory  are 
executed  according  to  the  same  scheme  as  in  68000-based  Amiga 
models.  This  requires  the  68030  to  constantly  insert  wait  states,  so  that 
the  result  is  a  maximum  of  one  access  every  560  nanoseconds.  During 
this  time  two  bus  cycles  elapse.  The  68030  can  use  every  other  bus 
cycle.  These  cycles  are  called  even  cycles.  The  remaining  cycles,  the  odd 
cycles,  are  reserved  exclusively  for  the  DMA  controller. 


788 


11.7  Programming  the  Hardware 


$o 


$8 


$10 


$18 


$20 


Refresh 


$28 


I 


£3 


Disk  DMA      Audio  DMA 


Earliest  possible  starting 
time  for  bit-plane  DMAs 


$30 


Data  fetch  start 
$38 


$40 


$48 


IL 
4  6 


LLL 


LL 
3  5 


16  low-res 
pixels 


$C4        $C8 


IL 

t  6 


32 


HHt 


35 


LL 

3  5 


32 


16hi-res 
pixels 

Data  fetch  stop 

$D0 


LL 


V  i  H  P  h  b 


32 


LL 
35 


L|- 
3 


HH 


HHHh  r 


H| 
2|1 


$D8 


$DF 


Bus  cycle  up  to 
$D8  is  the  same 
as  $40-$47 


3  5 


35 


LL 


LL 


HH 


LL 


HHH 

21  X 


LL 


LL 


HH 


LL 


HH 


4  32 


HH 


LL 


LL 
35 


Latest  possible  end  of 
bit-plane  DMAs 


Legend: 

R  =  Refresh  cycles 

D  =  Disk  DMA  cycles 

Ax=Audio  DMA  cycles,  x=channel  number 

Sx=Sprite  DMA  cycles,  x=sprite  number 

Lx=Low-res  bit-plane  DMA  cycles,  x=bit-plane  number 

Hx=High-res  bit-plane  DMA  cycles,  x=bit-plane  number 


fl 


=Even  bus  cycles  (processor  or  DMA)  |    =Odd  bus  cycles  (DMA  only) 


Raster  timing 

The  figure  shows  the  development  of  a  raster  line  over  time.  It  takes  63.5 
microseconds.  This  yields  227.5  bus  cycles  per  line.  Of  these  the  first  225 
can  be  taken  by  the  DMA  controller.  The  figure  shows  how  this  is  done: 
The  letters  within  the  individual  cycles  represent  the  corresponding 
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DMA  channels.  While  the  DMA  controller  has  exclusive  use  of  the  odd 
cycles,  it  must  share  the  even  ones  with  the  processor.  Still,  DMA  access 
always  takes  priority.  Blitter  DMA  and  Copper  DMA  always  take  place 
during  even  cycles.  There  is  no  defined  time  for  these  two,  but  once 
Copper  DMA  access  begins,  it  takes  all  the  even  cycles  until  it  has 
finished  its  task.  It  has  precedence  over  the  Blitter.  When  the  Blitter 
gains  access,  it  also  takes  all  the  even  cycles  until  it  is  finished.  Some 
cycles  can  still  be  left  free  for  the  68030. 

As  you  can  see,  disk,  audio  and  sprite  DMA  accesses  take  only  odd  bus 
cycles  and  do  not  affect  the  speed  of  the  processor.  The  four  cycles 
designated  "R"  are  refresh  cycles.  They  are  used  to  refresh  the  contents 
of  the  chip  RAM  (see  the  end  of  this  section). 

The  distribution  of  the  bit-plane  DMA  is  more  complicated.  For  the  first 
16  pixels  to  be  displayed  on  the  screen,  all  the  bit-planes  must  be  read. 
While  these  16  pixels  are  appearing  on  the  screen,  the  bit-planes  for  the 
next  16  pixels  must  be  read.  If  the  lowest  resolution  is  enabled,  two 
pixels  are  output  during  each  bus  cycle.  This  means  that  the  bit-planes 
must  be  read  every  eight  bus  cycles.  As  long  as  no  more  than  four  bit- 
planes  are  active,  the  odd  cycles  suffice.  If  five  or  six  planes  are  used,  two 
even  cycles  must  also  be  used  so  that  all  the  data  can  be  read  within  the 
eight  bus  cycles.  It's  even  tighter  in  high-resolution  mode.  Here  four 
pixels  are  displayed  per  bus  cycle.  If  only  odd  cycles  are  to  be  taken,  no 
more  than  two  hi-res  planes  can  be  active.  With  the  maximum  allowable 
number  of  four  hi-res  planes,  all  bus  cycles  are  taken.  As  a 
result,  the  processor  loses  more  than  half  of  its  free  bus  cycles.  Its  speed 
also  decreases  by  the  same  amount,  assuming  that  the 
current  program  is  in  the  chip  RAM,  since  the  processor  still  has  full- 
speed  access  to  any  fast  RAM  and  to  the  Kickstart  ROM. 

The  times  labeled  as  data  fetch  start  and  data  fetch  stop  designate  the 

start  and  stop  of  the  DMA  accesses  for  the  bit-planes.  They 

determine  the  width  and  horizontal  position  of  the  visible  picture.  If  the 

bit-plane  DMA  starts  early  and  ends  late,  more  data  words 

are  read  and  more  pixels  are  displayed.  The  normal  resolution  of  320  or 

640  pixels  per  line  can  be  varied  by  changing  these  values.  If 

the  data  fetch  start  is  set  below  $30,  the  bit-plane  DMA  channel  uses 

cycles  normally  reserved  for  sprite  DMA.  Depending  on  the 

exact  value  of  data  fetch  start,  up  to  seven  sprites  may  be  lost  this  way. 

Only  sprite  0,  which  is  generally  used  for  the  mouse  pointer, 

cannot  be  turned  off  in  this  manner. 
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The  top  line  in  the  figure  represents  the  division  of  the  DMA  cycles  for  a 
low-resolution  screen  with  the  normal  width  of  320  pixels.  The  start  of 
the  bit-plane  DMA,  data  fetch  start,  is  at  $38,  and  the  end,  data  fetch 
stop,  is  at  $D0.  The  data  from  bit-plane  number  1  is  read  in  the  cycles 
designated  LI,  the  bit-plane  2  data  in  L2,  and  so  on.  If  the  corresponding 
bit-planes  are  not  enabled,  their  DMA  cycles  are  also  omitted. 

The  second  line  represents  the  course  of  a  raster  line  in  which  the  data 
fetch  points  are  moved  outward.  Up  to  the  data  fetch  start  everything  is 
the  same  as  the  top  line,  but  here  the  DMA  starts  at  $28.  As  a  result, 
sprites  5  to  7  are  lost.  The  data  fetch  stop  position  is  moved  to  the  right 
to  the  maximum  value  of  $D8. 

The  third  line  shows  the  distribution  of  the  DMA  cycles  in  a  high- 
resolution  screen  where  the  data  fetch  values  match  those  of  the  first 
line. 

No  bit-plane  DMA  accesses  occur  during  the  vertical  blanking  gap. 

The  DMA  control  register 

The  individual  DMA  channels  are  enabled  and  disabled  through  a  central 
DMA  control  register,  DMACON. 

The  DMACON  register  addresses  are  $096  (write)  and  $02  (read) 


Bit 

Name 

Function  (when  set) 

15 

SET/CLR 

Set/clear  bits 

14 

BBUSY 

Blitter  busy  (read  only) 

13 

BZERO 

Result  of  all  Blitter  operations  is  0  (read  only) 

12  and  11 

Unused 

10 

BLTPRI 

Blitter  DMA  has  priority  over  processor 

9 

DMAEN 

Enable  all  DMA  (for  bits  0  to  8) 

8 

BPLEN 

Enable  bit-plane  DMA 

7 

COPEN 

Enable  Copper  DMA 

6 

BLTEN 

Enable  Blitter  DMA 

5 

SPREN 

Enable  sprite  DMA 

4 

DSKEN 

Enable  disk  DMA 

3-0 

AUDxEN 

Enable  audio  DMA  for  sound  channel  x  (bit 
number  corresponds  to  number  of  sound 

channel) 

The  DMACON  register  is  not  written  like  a  normal  register.  You  can  only 
set  or  clear  bits.  This  is  determined  by  bit  15  of  the  data  word  written  to 
the  DMACON  register.  If  this  bit  is  1,  all  the  bits  that  are  set  in  the  data 
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word  are  also  set  in  the  DMACON  register.  If  bit  15  is  0,  all  the  bits  that 
are  set  in  the  data  word  are  cleared  in  the  DMACON  register.  The 
remaining  bits  in  DMACON  remain  unaffected. 

Bit  9,  designated  DMAEN,  is  something  of  a  main  switch.  If  it  is  0,  all 
DMA  channels  are  inactive,  regardless  of  bits  0  to  8.  To  enable  DMA  you 
must  set  both  the  appropriate  DMA  channel  bit  and  the  DMAEN  bit. 
Here  is  an  example: 

Only  the  bit-plane  DMA  is  enabled  (BPLEN  =1),  but  without  the 
DMAEN  bit.  The  value  of  the  DMACON  register  is  $0100.  Now  you 
want  to  enable  the  disk  DMA.  DSKEN  and  DMAEN  must  be  set  and 
BPLEN  cleared. 

MOVE.W  #$0100,$DFF096       ,-Clears  the  BPLEN  bit  (SET/CLR  =  0) 
MOVE.W  #$8210,$DFF096       ;Sets  DSKEN  and  DMAEN  (SET/CLR  =  1) 

The  DMACON  register  now  contains  the  desired  value  of  $0210.  Bits  13 
and  14  can  only  be  read.  They  supply  information  about  the  status  of  the 
Blitter,  which  is  discussed  in  more  detail  in  the  Blitter  section. 

Bit  10  controls  the  priority  of  the  Blitter  over  the  processor.  If  it  is  set,  the 
Blitter  has  absolute  priority  over  the  68030.  This  may  go  so  far  as  to 
deny  the  processor  all  access  to  the  chip  registers  and  chip  RAM 
throughout  the  entire  Blitter  operation.  When  it  is  cleared,  the  processor 
gets  every  fourth  even  bus  cycle  from  the  Blitter.  This  prevents  the 
processor  from  being  held  up  when  an  operating  system  routine  or  a 
program  in  fast  RAM,  both  of  which  execute  at  full  speed,  must  access 
chip  RAM,  for  example,  to  get  an  operating  system  data  structure  or  a 
68030  exception  vector. 

Reading  the  current  electron  beam  position 

Since  all  DMA  timing  is  oriented  according  to  the  position  within  a  raster 
line,  it  is  sometimes  useful  to  know  where  on  the  line  the  electron  beam  is 
currently  located.  Agnus  has  an  internal  counter  for  this,  which  contains 
both  the  horizontal  and  vertical  screen  position.  Two  registers  allow  the 
processor  access  to  this  counter: 
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VHPOS  $006  (read,  VHPOSR)  and  $02C  (write,  VHPOSW) 


Bit  no.:         15     14     13     12     11     10     9       8       7       6       5       4       3       2       1       0 
Function:     V7    V6    V5    V4    V3    V2    V1     V0    H8    H7    H6    H5    H4    H3    H2    H1 


VPOS  $004  (read,  VPOSR)  and$02A  (write,  VPOSW) 


Bit  no.:        15       14     13     12     11     10    9 
Function:    LOF 


8 


2       1       0 
V10V9    V8 


The  bits  designated  HI  to  H8  represent  the  horizontal  beam  position  and 
correspond  directly  to  the  numbers  for  the  individual  bus  cycles  in  the 
figure.  They  have  a  precision  of  two  low  or  four  high-resolution  pixels. 
The  value  for  the  horizontal  position  can  vary  between  $0  and  $E3  (0  to 
227).  The  horizontal  blanking  gap  falls  in  the  range  from  $F  to  $35. 

The  bits  for  the  vertical  position,  the  current  screen  line,  span  both 
registers.  The  lower  bits,  V0-V7,  are  in  VHPOS,  and  the  upper  bits,  V8- 
V10,  are  in  VPOS.  Together  they  yield  the  number  of  the  current  screen 

line. 

Lines  from  0  to  312  are  possible.  The  vertical  blanking  gap  (the  screen  is 
always  dark  in  this  range)  runs  from  line  0  to  line  25.  The  LOF  (LOng 
Frame)  bit  indicates  whether  the  image  currently  being  displayed  is  a 
long  (odd  lines)  or  short  (even  lines)  frame.  This  bit  is  needed  only  in 
interlace  mode.  Normally  it  is  1. 

The  beam  position  can  also  be  set,  but  this  capability  is  rarely  needed. 
The  POS  registers  have  another  function  in  connection  with  a  light  pen. 
When  the  lightpen  input  of  Agnus  is  activated  and  the  lightpen  is  held 
against  the  screen,  they  store  its  position.  This  means  that  their  contents 
are  frozen  as  soon  as  the  lightpen  detects  the  electron  beam  moving  past 
its  tip.  The  counters  are  released  again  at  the  end  of  the  vertical  blanking 
gap,  line  26.  To  read  the  lightpen  position,  you  must  proceed  as  follows: 

•  Wait  for  line  0  (start  of  the  vertical  blanking  gap).  This  is  most  easily 
done  by  means  of  the  vertical  blanking  interrupt  (see  next  section). 

•  Read  the  two  counter  registers. 
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If  the  vertical  position  is  between  0  and  25  (within  the  vertical  blanking 
gap),  no  lightpen  signal  was  received.  If  the  value  is  outside  this  range,  it 
represents  the  position  of  the  lightpen. 

To  conclude  this  section,  here  are  some  more  details  about  the  refresh 
cycles: 

Agnus  possesses  an  integrated  9-bit  refresh  counter.  It  can  be  written 
through  register  address  $28  (be  careful  because  the  memory  contents 
can  be  lost  this  way).  At  the  start  of  each  raster  line,  Agnus  places  four 
refresh  addresses  on  the  chip  RAM  address  bus.  This  means  the  contents 
of  each  memory  row  are  refreshed  every  four  milliseconds. 

While  the  row  address  is  being  output  on  the  chip  RAM  address  bus, 
Agnus  places  the  addresses  of  certain  strobe  registers  on  the  register 
address  bus.  These  strobe  signals  serve  to  inform  the  other  chips,  Denise 
and  Paula,  of  the  start  of  a  raster  line  or  a  picture.  This  is  necessary 
because  the  counter  for  the  screen  position  is  inside  Agnus  and  there  are 
no  lines  for  transmitting  the  synchronization  signals  to  the  other  chips. 
There  are  four  strobe  addresses: 


Addr. 

Chip 

Function 

$38 

D 

Vertical  blanking  gap  of  a  short  frame 

$3A 

D 

Vertical  blanking  gap 

$3C 

DP 

This  strobe  address  is  created  in  every  raster  line 
outside  the  vertical  blanking  gap 

$3E 

D 

Marker  for  a  long  raster  line  (228  cycles) 

During  the  first  refresh  cycle,  one  of  the  first  three  strobe  addresses  is 
always  referenced.  Normally  this  is  $3C,  and  within  the  vertical  blanking 
gap  $38  or  $3A,  depending  on  whether  it  is  a  short  or  long  frame. 

With  the  fourth  address  the  situation  is  as  follows:  A  raster  line  has  a 
purely  computational  length  of  227.5  bus  cycles.  But  since  there  are  no 
half-cycles,  lines  alternate  between  227  and  228  bus  cycles.  The  strobe 
address  $3E  signals  the  228-cycle  lines  and  is  created  during  the  second 
refresh  cycle. 


11.7.3        Interrupts 


Almost  all  the  I/O  components  of  the  custom  chips  and  the  two  CIAs  can 
generate  an  interrupt.  A  special  circuit  inside  Paula  manages  the  interrupt 
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sources  and  creates  the  interrupt  signals  for  the  68030.  The  processor's 
autovector  interrupts,  levels  0  to  6,  are  used  for  this.  No  provision  is  made 
for  the  non-maskable  interrupt  (NMI),  level  7.  The  two  registers  involved 
are  the  interrupt  request  register  (INTREQ)  and  the  interrupt  mask 
(enable)  register  (INTENA).  The  assignment  of  the  bits  in  the  two 
registers  is  identical. 

Interrupt  enable  and  interrupt  request  register  layout 


INTREQ 
INTREQR 
INTENA 
INTENAR 


=  $09C  (write) 
=  $01E(read) 
=  $09A  (write) 
=  $01C(read) 


Bit 

Name 

IE 

Function 

15 

SET/CLR 

Write/read  (see  DMACON  register) 

14 

INTEN 

(6) 

Enable  interrupts 

13 

EXTER 

6 

Interrupt  from  CIA-B  or  expansion  port 

12 

DSKSYN 

5 

Disk  sync  value  recognized 

11 

RBF 

5 

Serial  port  receive  buffer  full 

10 

AUD3 

4 

Output  audio  data  channel  3 

9 

AUD2 

4 

Output  audio  data  channel  2 

8 

AUDI 

4 

Output  audio  data  channel  1 

7 

AUDO 

4 

Output  audio  data  channel  0 

6 

BUT 

3 

Blitter  ready 

5 

VERTB 

3 

Start  of  vertical  blanking  gap  reached 

4 

COPER 

3 

Reserved  for  Copper  interrupts 

3 

PORTS 

2 

Interrupt  from  CIA-A  or  expansion  port 

2 

SOFT 

1 

Reserved  for  software  interrupts 

1 

DSKBLK 

1 

Disk  DMA  transfer  ended 

0 

TBE 

1 

Serial  transmit  buffer  empty 

The  lower  13  bits  represent  the  individual  interrupt  sources.  The  CIA 
interrupts  are  combined  into  a  single  interrupt.  The  bits  in  the  DMAREQ 
register  indicate  which  interrupts  have  occurred.  A  bit  is  set  if  the 
corresponding  interrupt  has  occurred.  In  order  to  generate  a  processor 
interrupt,  the  corresponding  bit  must  be  set  in  the  DMAENA  register  and 
the  INTEN  bit  must  also  be  set.  The  INTEN  bit  acts  as  the  main  switch  for 
the  remaining  14  interrupt  sources,  which  can  be  turned  on  and  off  with 
the  individual  bits  of  the  INTENA  register.  Only  when  INTEN  is  1  can 
any  interrupts  be  generated. 

If  both  the  INTEN  bit  and  the  two  corresponding  bits  in  the  INTENA  and 
INTREQ  registers  are  set,  a  processor  interrupt  is  generated. 
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The  corresponding  autovector  numbers  are  listed  in  the  IL  (Interrupt 
Level)  column  in  the  table.  Here  are  the  addresses  of  the  seven  interrupt 
auto  vectors: 


Vector  no. 

Address 

Autovector  level 

25 

100/$64+(VBR) 

Autovector  level  1 

26 

104/$68+(VBR) 

Autovector  level  2 

27 

108/$6C+(VBR) 

Autovector  level  3 

28 

112/$70+(VBR) 

Autovector  level  4 

29 

116/$74+(VBR) 

Autovector  level  5 

30 

120/$78+(VBR) 

Autovector  level  6 

(31 

124/$7C+(VBR) 

Autovector  level  7) 

VBR  =  Vector  Base  Register  (see  section  on  68030) 

As  you  can  see,  the  interrupts  that  require  faster  processing  are  given 
higher  interrupt  levels.  To  change  the  bits  in  these  two  registers,  you 
must  work  with  a  SET/CLR  bit  using  the  same  procedure  described  for 
the  DMACON  register. 

After  processing  an  interrupt,  the  processor  must  reset  the  INTREQ 
register  bit  that  generated  it.  In  contrast  to  the  interrupt  control  registers 
of  the  CIAs,  the  bits  in  the  INTREQ  register  are  not  automatically  cleared 
on  reading. 

Setting  a  bit  in  the  INTREQ  register  with  a  MOVE  command  has  the 
same  effect  as  if  the  corresponding  interrupt  had  occurred.  This  is  how  a 
software  interrupt  is  created,  for  example  (SOFT,  bit  2).  The  Copper  can 
also  create  its  own  interrupt  by  writing  into  INTREQ. 

One  peculiarity  is  bit  14  in  the  INTREQ  register,  which  has  no  specific 
function  there  as  it  does  in  INTENA.  But  when  it  is  set  by  writing  to 
INTREQ,  and  ENTEN  in  the  INTENA  register  is  high,  a  level  6  interrupt  is 
generated. 

On  each  interrupt  from  CIA-A,  bit  3  in  the  DMAREQ  register  is  set.  For 
CIA-B  this  is  bit  13.  The  interrupt  source  in  the  corresponding  CIA  must 
be  determined  by  reading  the  interrupt  control  register  of  the  CIA. 
Interrupts  3  and  13  can  also  be  generated  by  expansion  cards  on  the 
expansion  port. 

Interrupt  bit  5  indicates  the  vertical  blanking  interrupt.  This  occurs  at  the 
start  of  each  video  frame  at  the  start  of  the  vertical  blanking  gap  (line  0), 
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and  SO  times  per  second.  The  remaining  interrupts  are  discussed  in  the 
appropriate  sections. 

11.7.4        The  Copper  Coprocessor 

The  Copper  is  a  simple  coprocessor.  It  writes  certain  values  into  the 
various  registers  of  the  custom  chips  automatically  at  defined  points  in 
time.  More  accurately,  the  Copper  can  change  the  contents  of  some 
registers  at  any  screen  position.  By  doing  so,  it  can  divide  the  screen  into 
different  regions,  which  can  then  have  different  colors  and  resolutions. 
For  example,  this  capability  is  used  to  implement  multiple  screens. 

The  Copper  is  designated  a  coprocessor  because,  like  a  real  processor,  it 
has  a  program  stored  in  memory  that  executes  command  by  command. 
The  Copper  recognizes  only  three  different  commands,  but  they  are  quite 
versatile: 

MOVE 

The  MOVE  command  writes  an  immediate  value  into  a  custom  chip 
register. 

WAIT 

The  WAIT  command  waits  until  the  electron  beam  reaches  a  certain 
screen  position. 

SKIP 

The  SKIP  command  skips  the  next  command  if  the  electron  beam  has 
already  reached  a  certain  screen  position.  This  allows  conditional 
branches  to  be  built  into  the  program. 

A  Copper  program  is  called  a  Copper  list.  It  is  a  series  of  consecutive 
instructions,  each  consisting  of  two  words.  For  example: 

Wait  (XI, Yl)  ;waits  until  screen  position  XI, Yl  is  reached 

Move  #0,$180  ;writes  the  value  0  to  the  background  color  register 

Move  #9,  $181  ,-writes  the  value  1  to  color  register  1 

Wait  (X2,Y2)  ;waits  until  screen  position  X2,Y2  is  reached 

...  etc. 
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The  Copper  list  alone  is  not  sufficient  to  operate  the  Copper.  Other 
registers  are  required  which  contain  parameters  needed  by  the  Copper. 


The  Copper  register 


Reg. 

Name 

Function 

$080 

COP1LCH 

These  two  registers  together  contain  the 

$082 

COP1LCL 

20-bit  address  of  the  first  Copper  list. 

$084 

COP2LCH 

These  two  registers  together  contain  the 

$086 

COP2LCL 

20-bit  address  of  the  second  Copper  list. 

$088 

COPJMP1 

Loads  the  address  of  the  first  Copper  list  into 
the  Copper  program  counter. 

$08A 

COPJMP2 

Loads  the  address  of  the  second  Copper  list 
into  the  Copper  program  counter. 

$02E 

COPCON 

This  register  contains  only  a  single  bit  (bit  0).  If  it  is 
set,  the  Copper  can  also  access  the  registers  from 
$040  to  $7E.  (These  belong  to  the  Blitter.) 

All  the  Copper  registers  are  write-only  registers. 

The  COPxLC  registers  contain  addresses  of  Copper  lists.  Since  such  an 
address  is  19  bits  long,  two  registers  are  needed  per  address.  Both 
registers  of  a  pair  can  be  written  with  one  MOVE.L  command  to  the  first 
register.  The  Copper  lists,  like  all  other  data  for  the  custom  chips,  must  lie 
within  the  2  Meg  chip  RAM. 

The  Copper  uses  an  internal  counter  as  a  pointer  to  the  current 
command.  It  is  incremented  by  two  each  time  a  command  is  processed. 
To  start  the  Copper  at  a  given  address,  the  start  address  of  the  Copper  list 
must  be  transferred  to  the  program  counter.  The  COPJMPx  registers  are 
used  for  this.  They  are  strobe  registers,  meaning  that  a  write  access  to  one 
of  them  simply  activates  a  particular  action  —  they  are  not  used  to  store 
actual  values.  The  values  written  to  them  are  completely  irrelevant. 

In  the  Copper  these  two  registers  cause  the  contents  of  the 
corresponding  COPxLC  registers  to  be  copied  into  the  program  counter. 
If  a  write  access  is  made  to  COPJMP1,  the  address  in  COP1LC  is  copied 
into  the  program  counter,  which  causes  the  Copper  to  execute  the 
program  at  that  address.  This  also  applies  to  COPJMP2  and  COP2LC. 

At  the  start  of  the  vertical  blanking  gap,  line  0,  the  program  counter  is 
automatically  loaded  with  the  value  from  COP1LC.  This  causes  the 
Copper  to  execute  the  same  program  for  every  picture. 
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The  command  structure 


MOVE 

WAIT 

SKIP 

Bit 

BW1 

BW2 

BW1 

BW2 

BW1 

BW2 

15 

X 

DW15 

VP7 

BFD 

VP7 

BFD 

14 

X 

DW14 

VP6 

VM6 

VP6 

VM6 

13 

X 

DW13 

VP5 

VM5 

VP5 

VM5 

12 

X 

DW12 

VP4 

VM4 

VP4 

VM4 

11 

X 

DW11 

VP3 

VM3 

VP3 

VM3 

10 

X 

DW10 

VP2 

VM2 

VP2 

VM2 

9 

X 

DW9 

VP1 

VM1 

VP1 

VM1 

8 

RA8 

DW8 

VPO 

VMO 

VPO 

VMO 

7 

RA7 

DW7 

HP8 

HM8 

HP8 

HM8 

6 

RA6 

DW6 

HP7 

HM7 

HP7 

HM7 

5 

RA5 

DW5 

HP6 

HM6 

HP6 

HM6 

4 

RA4 

DW4 

HP5 

HM5 

HP5 

HM5 

3 

RA3 

DW3 

HP4 

HM4 

HP4 

HM4 

2 

RA2 

DW2 

HP3 

HM3 

HP3 

HM3 

1 

RA1 

DW1 

HP2 

HM2 

HP2 

HM2 

0 

0 

DWO 

1 

0 

1 

1 

Legend: 

x  This  bit  is  unused.  It  should  be  initialized  to  0. 

RA  Register  address 

DW  Data  word 

VP  Vertical  beam  position 

VM  Vertical  mask  bits 

HP  Horizontal  beam  position 

HM  Horizontal  mask  bits 

BFD  Blitter  finish  disable 

The  MOVE  command 

The  MOVE  command  is  indicated  by  a  0  in  bit  0  of  the  first  command 
word.  With  this  command  it  is  possible  to  write  an  immediate  value  to  a 
custom  chip  register.  The  register  address  of  the  desired  register  comes 
from  the  lower  9  bits  of  the  first  data  word.  Bit  0  must  always  remain  0  (it 
is  already  0  for  the  register  addresses  because  the  registers  lie  only  on 
even  addresses).  The  second  command  word  contains  the  data  byte  to  be 
written  to  the  register. 

There  are  some  limitations  regarding  the  register  address.  Normally  the 
Blitter  cannot  affect  the  registers  in  the  range  from  $000  to  $07F.  If  the 
lowest  (and  only)  bit  in  the  COPCON  register  is  set,  then  the  Copper  can 
write  to  the  registers  in  the  range  from  $040  to  $07F.  This  allows  the 
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Copper  to  use  the  Blitter.  Access  to  the  lowest  registers  ($000  to  $03F) 
is  never  allowed. 

The  WAIT  command 

The  WAIT  command  is  indicated  by  a  1  in  bit  0  of  the  first  word  and  a  0 
in  bit  0  of  the  second  word.  It  instructs  the  Copper  to  hold  further 
execution  until  the  desired  beam  position  is  reached.  If  the  position  is 
already  greater  than  that  specified  by  the  WAIT  command  at  the  time  the 
command  is  executed  (the  beam  is  already  past  the  specified  position), 
the  Copper  continues  with  the  next  instruction  immediately. 

This  position  can  be  set  separately  for  the  vertical  lines  and  horizontal 
rows.  Vertically  the  resolution  is  one  raster  line.  But  since  there  are  only 
eight  bits  for  the  vertical  position  and  there  are  313  lines,  the  WAIT 
command  cannot  distinguish  between  the  first  256  and  the  remaining  57 

lines. 

For  example,  the  lowest  eight  bits  are  the  same  for  both  line  0  and  line 
256.  To  wait  for  a  line  in  the  lower  range,  two  wait  commands  must  be 
used. 

1.  WAIT  for  line  255  column  224  ($FFE1 ). 

2.  WAIT  for  the  desired  line,  ignoring  the  ninth  bit. 

Horizontally  there  are  112  possible  positions,  since  the  two  lower  bits  of 
the  horizontal  position,  HPO  and  HP1,  cannot  be  specified.  The  command 
word  of  the  WAIT  command  holds  only  bits  HP2  to  HP8.  This  means  that 
the  horizontal  coordinate  of  a  WAIT  command  can  only  be  specified  in 
steps  of  four  low-resolution  pixels. 

The  second  command  word  contains  mask  bits.  These  can  be  used  to 
determine  which  bits  of  the  horizontal  and  vertical  position  are  actually 
considered  in  the  comparison  with  the  current  beam  position.  Only  the 
position  bits  whose  mask  bits  are  set  are  considered.  This  opens  up  many 
possibilities.  For  example: 


Wait  for  vertical  position  $0F  and  vertical  mask  $0F 


causes  the  WAIT  condition  to  be  fulfilled  every  16  lines  (whenever  the 
lower  four  bits  are  all  1),  since  bits  4  to  6  are  not  considered  (mask  bits  4 
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to  6  are  at  0).  The  seventh  bit  of  the  vertical  position  cannot  be  masked. 
The  previous  example  works  only  in  the  range  of  lines  0  to  127  and  256 
to  313. 

The  BFD  (Blitter  Finish  Disable)  bit  has  the  following  function:  If  the 
Copper  is  used  to  start  a  Blitter  operation,  it  must  know  when  the  Blitter 
is  finished  with  the  previous  operation.  If  the  BFD  bit  is  cleared,  the 
Copper  waits  at  every  WAIT  command  until  the  Blitter  has  finished  its 
operation.  Only  then  is  the  WAIT  condition  checked.  This  can  be 
prevented  by  setting  the  BFD  bit,  causing  the  Copper  to  ignore  the 
current  Blitter  status.  If  the  Copper  shouldn't  affect  any  of  the  Blitter 
registers,  this  bit  is  set  to  1. 

The  SKIP  command 

The  SKIP  command  is  identical  to  the  WAIT  command,  except  that  bit  0 
in  the  second  command  word  is  set  to  distinguish  it  from  the  WAIT 
command.  The  SKIP  command  checks  to  see  if  the  actual  beam  position 
is  greater  than  or  equal  to  that  given  in  the  command  word.  If  this 
comparison  is  positive,  the  Copper  skips  the  next  command.  Otherwise  it 
continues  program  processing  by  executing  the  next  command.  The 
SKIP  command  allows  conditional  branches  to  be  constructed.  The 
command  following  SKIP  can  be  a  MOVE  into  one  of  the  COPJMP 
registers,  causing  a  jump  to  be  made  based  on  the  beam  position. 

t 

Construction  of  a  Copper  list 

A  simple  Copper  list  consists  of  a  sequence  of  WAIT  and  MOVE 
commands,  and  a  few  SKIP  commands.  Its  start  address  is  found  in 
COPLC1.  A  trick  must  be  used  to  end  the  Copper  list.  After  the  last 
instruction  comes  a  WAIT  command  with  an  impossible  beam  position. 
This  effectively  ends  the  processing  of  the  Copper  list  until,  at  the  start  of 
a  new  picture,  the  COPLC1  address  is  loaded  into  the  program  counter 
again  to  restart  processing.  WAIT  ($0,$FE)  fulfills  this  condition,  because 
a  horizontal  position  greater  than  $E4  is  not  possible. 

The  Copper  interrupt 

As  you  know,  there  is  a  special  bit  in  the  interrupt  registers  for  the 
Copper  interrupt.  This  interrupt  can  be  generated  with  a  MOVE 
command  to  the  INTREQ  register: 
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MOVE  #$8010,INTREQ         ;set  SET/CLR  and  COPER 


Any  other  bit  in  this  register  can  be  affected  the  same  way,  but  bit  4  is 
provided  especially  for  the  Copper. 

A  Copper  interrupt  can  be  used  to  tell  the  processor  that  a  certain  screen 
position  has  been  reached.  This  allows  what  are  called  raster  interrupts  to 
be  programmed  (i.e.,  the  interruption  of  the  processor  in  a  certain  screen 
line  (and  column)). 

The  Copper  DMA 

The  Copper  fetches  its  commands  from  memory  through  its  own  DMA 
channel.  It  uses  the  even  bus  cycles  and  has  precedence  over  the  Blitter 
and  the  68030.  Each  command  requires  two  cycles,  since  two  command 
words  must  be  read.  The  WAIT  command  requires  an  additional  cycle 
when  the  desired  beam  position  is  reached.  The  Copper  leaves  the  bus 
free  during  the  wait  phase  of  a  WAIT  command. 

The  COPEN  bit  in  the  DMACON  register  is  used  to  turn  the  Copper 
DMA  on  and  off.  If  this  bit  is  cleared,  the  Copper  releases  the  bus  and 
does  not  execute  any  more  commands.  If  it  is  set,  it  starts  its  program 
execution  at  the  address  in  its  program  counter.  Therefore,  it  is  absolutely 
necessary  to  supply  this  with  a  valid  address  before  starting  the  Copper 
DMA.  A  Copper  running  in  an  unknown  area  of  memory  can  crash  the 
system.  The  usual  initialization  sequence  for  the  Copper  looks  like  this: 

LEA    $DFF000,A5  ;Base  address  of  registers  to  A5 

MOVE.W  #$0080,DMACON(A5)         ;Copper  DMA  off 

MOVE.L  #Copperlist,COPlLCH(A5)   ;Set  address  of  Copper  list 

COPJMPl(A5)  ,-Transfer  this  address  to  Copper  program 

; counter 
MOVE.W  #$8080,DMACON(A5)         ,-enable  Copper  DMA 

Sample  program 

Finally,  here  is  a  sample  program.  It  uses  two  WAIT  commands  and  three 
MOVE  commands  to  display  black,  red  and  yellow  bars  on  the  screen.  It 
can  be  created  with  a  simple  Copper  list  and  offers  a  good  example. 
Enter  the  program  with  a  standard  assembler  for  the  Amiga  (such  as 
AssemPro): 
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,-***  Example  for  a  simple  Copper  list  *** 
;CustomChip-Register 


INTENA  =  $9A 
DMACON  =  $96 
COLOR00  =  $180 

; Copper-Register 

COP1LC  =  $80 
COP2LC  =  $84 
COPJMP1  =  $88 
COPJMP2  =  $8a 


;Interrupt-Enable  register  (write) 
•DMA-Control  register  (write) 
; Color  palette  register  0 


;Address  of  1st  Copper  list 

/Address  of  2nd  Copper  list 

;Jump  to  Copper  list  1 

;Jump  to  Copper  list  2 


;CIA-A  Port  register  A  (Mouse  key) 

CIAAPRA  =  $BFE001 

;Exec  Library  Base  Offsets 


OpenLibrary  =  -30-522 
Forbid   =  -30-102 
Permit   =  -30-108 
AllocMem  =  -30-168 
FreeMem  =  -30-180 

; graphics  base 

StartList  =  38 

; Other  Labels 

Execbase  =  4 

Chip  =  2  ; Request  Chip-RAM 

;***  Initialize  program  *** 

/Request  memory  for  Copper  list 

Start : 

move.l  Execbase, a6 

moveq  #Clsize,d0 

moveq  #chip,dl 

jsr  AllocMem(a6) 


; LibName , Vers  ion/al , dO 


; ByteSize, Requirements/dO , dl 
;MemoryBlock, ByteSize/al, dO 


;Set  parameters  for  AllocMem 
;ask  for  Chip-RAM 
.•request  memory 
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move .1  dO , CLadr 
beq .  s  Ende 

;Copy  Copper  list  to  CLadr 

lea    CLstart.aO 
move . 1  CLadr , al 
moveq   #CLsize-l,dO 
CLcopy : 

move.b  (a0)+, (al)+ 
dbf    dO , CLcopy 

;***  Main  program  *** 

jsr    forbid (a6) 
lea    $dff000,a5 
move.w  #$03a0,dmacon(a5) 
move . 1  CLadr , copl lc ( a5 ) 
clr.w  copjmpl(a5) 

;Turn  on  Copper-DMA 

move.w  #$8280,dmacon(a5) 

;Wait  for  left  mouse  key 

Wait:  btst  #6,ciaapra 
bne.s  Wait 

;***  End  program  *** 

(•Reactivate  old  Copper  list 

move . 1  #GRname , a 1 

clr.l  dO 

jsr    0penLibrary(a6) 

move .1  dO ,  a4 

move.l  StartList (a4) , copllc(a5) 

clr.w  copjmpl(a5) 

move.w  #$83e0,dmacon(a5) 

jsr    permit (a6) 

;Free  memory  of  Copper  list 


; Store  address  of  RAM  area 
; Error!  ->  End 


;Set  loop  counter 

;Copy  Copper  list  byte  by  byte 


; Task-switching  off 

;Base  address  of  registers  to  A5 

;DMA  off 

/Address  of  Copper  list  to  C0P1LC 

;Load  address  to  Copper  program  counter 


;Test  bit 

;Set?  Then  wait. 


;Set  parameters  for  OpenLibrary 

;Open  Graphics  Library 
/Address  of  GraphicsBase  to  a4 
;Load  address  of  Startlist 

;A11  necessary  DMA  channels  on 
; Task-switching  on 


move.l  CLadr, a 1 
moveq  #CLsize,dO 


;Set  parameters  for  FreeMem 
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Ende: 

clr.l   dO 
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;Free  memory 

;Clear  error-flag 
;End  program 


;Variables 
CLadr:  del  0 
; Constants 


GRname:  dc.b  "graphics . library" , 0 
even 


; align 


; Copper-List 


CLstart : 

dew  color00,$0000 
dew  $780f,$fffe 
dew  color00,$0f00 
dew  $d70f,$fffe 
dew  color00,$0fb0 
dew  $ffff,$fffe 
CLend : 


; Background  color  black 

;Wait  for  line  120 

; Switch  to  red 

;Line  215 

;Gold 

.•Impossible  position:  End  Copper-List 


CLsize  =  CLend  -  CLstart 


;End  of  program 


This  program  installs  the  Copper  list  and  then  waits  until  the  left  mouse 
button  is  pressed.  Unfortunately,  this  isn't  as  easy  as  it  sounds. 

First,  you  need  memory  in  which  to  store  the  Copper  list.  Like  all  data  for 
the  custom  chips,  it  must  be  in  the  chip  RAM.  Since  you  can't  be  sure 
whether  the  program  is  actually  in  the  chip  RAM,  it  is  necessary  to  copy 
the  Copper  list  into  the  chip  RAM.  In  a  multitasking  operating  system 
like  that  of  the  Amiga,  you  can't  just  write  something  into  memory;  you 
must  request  the  memory.  This  is  done  in  the  program  with  the  AllocMem 
routine.  This  returns  the  address  of  the  requested  chip  RAM  in  DO.  The 
Copper  list  is  then  copied  into  memory  at  this  address. 

Next,  the  task  switching  is  disabled  by  a  call  to  Forbid  so  that  the  Amiga 
processes  only  your  program.  This  prevents  your  program  from  being 
disturbed  by  another. 
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Finally,  the  Copper  is  initialized  and  started.  After  this,  the  program  tests 
for  the  left  mouse  button  by  reading  the  appropriate  port  bit  of  CIA-A.  If 
the  mouse  button  is  pressed,  the  processor  exits  the  wait  loop. 

To  get  back  to  the  old  display,  a  special  Copper  list  is  loaded  into  the 
Copper  and  started.  This  Copper  list  is  called  the  startup  Copper  list  and 
it  initializes  the  screen.  Its  address  is  found  in  the  variable  area  for  the 
part  of  the  operating  system  responsible  for  the  graphics  functions.  At 
the  end,  task  switching  is  re-enabled  with  Permit  and  the  occupied 
memory  is  released  again  with  FreeMem. 

This  program  contains  a  number  of  operating  system  functions,  which 
you  are  probably  not  familiar  with  yet.  Unfortunately,  this  cannot  be 
avoided  if  you  want  to  make  the  program  work  correctly.  But  it  doesn't 
matter  if  you  don't  understand  everything  yet.  We  are  discussing  the 
Copper  in  this  section,  and  this  part  of  the  program  should  be 
understandable.  In  the  later  sections  of  this  book  you'll  discover  the 
secrets  of  the  operating  system  and  its  routines.  Enter  this  example  and 
experiment  with  the  Copper  list.  Change  the  WAIT  command  or  add  new 
ones.  You  can  also  experiment  with  a  SKIP  command. 


Copper   list 


Address   Command 


Copper  active 


n    MOVE  #black,  COLOR00 
n+2  WAIT  0,100 


n+6   MOVE  #red,COLOR00 
n=6  WAIT  0,190 

n+8   MOVE  #gold,COLOR00 
n+10  WAIT  254,255 


Line 


u 
120 

y/////A 

VBlack  V 

—Red  = 

215 

Gold 

The  Copper  list 

One  more  thing  about  the  Copper  list:  The  two  WAIT  commands  contain 
$E  as  the  horizontal  position.  This  is  the  start  of  the  horizontal  blanking 
gap.  This  way  the  Copper  performs  the  color  switch  outside  the  visible 
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area.  If  0  is  used  as  the  horizontal  position,  the  color  switching  can  be 
seen  at  the  extreme  right  edge  of  the  screen. 


11.7.5        Playfields 


The  screen  output  of  the  Amiga  consists  of  two  basic  elements:  sprites 
and  playfields.  In  this  section  we'll  discuss  the  structure  and 
programming  of  all  types  of  playfields.  The  playfield  is  the  basis  of  the 
normal  screen  display.  It  consists  of  one  to  six  bit-planes.  A  playfield  is  a 
graphic  screen  that  is  built  up  from  a  variable  number  of  individual 
memory  areas  (the  bit-planes).  The  Amiga  provides  various  ways  to 
display  playfields: 

Between  2  and  4096  colors  simultaneously  in  one  picture. 

•  Resolutions  of  16  by  1  to  736  by  568  pixels. 

•  Two  completely  independent  playfields  are  possible. 

•  Smooth  scrolling  in  both  directions. 

All  these  capabilities  can  be  divided  into  two  groups. 

1.  Combining  the  bit-planes  to  achieve  the  colors  of  the  individual 
pixels  (displaying  the  bit  pattern  from  the  bit-planes). 

2.  Determining  the  form,  size  and  position  of  the  playfields(s). 

The  various  display  options 

By  using  from  1  to  6  bit-planes,  you  are  using  the  corresponding  number 
of  bits  to  represent  each  pixel.  This  value  must  then  be  converted  into 
one  of  4096  colors,  since  each  pixel  can  naturally  have  only  one  color. 

The  Amiga  creates  its  colors  by  mixing  the  component  colors,  red,  green 
and  blue.  Each  of  these  three  components  can  have  16  different  intensity 
levels.  This  results  in  4096  color  shades  (16*16*16  =  4096).  Storing  a 
color  value  requires  four  bits  per  component,  or  12  bits  per  color. 

If  you  wanted  to  allow  one  of  4096  colors  for  each  pixel,  you  would 
need  12  bits  per  pixel.  But  a  maximum  of  six  bits  is  possible.  Therefore, 
the  six  bits  must  be  converted  into  one  of  the  4096  possible  colors  for 
the  visible  point. 
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The  color  palette 

A  color  palette  or  color  table  is  used  to  do  this.  On  the  Amiga  this 
contains  32  entries,  each  of  which  can  hold  a  12-bit  color  value.  The 
value  of  the  first  color  register  COLOR00  is  used  for  the  background 
color  and  the  border  color. 


1st  color  choice  from  color  table 


S-blt  number  from  blt-plane= 
pointer  to  color  table 


Color  table 


°E 


<I> 


0 in  Bii-pi^rr 


COLOR   00 


COLOR    01 


COLOR   02 


COLOR  03 


COLOR  04 


COLOR  05 


COLOR   06 


COLOR   07 


0 1    ■    I    tit    II   ■,„■„■,,„»    * 


.POLOR   08 


1|    I    I    I    I    I    I    IBM-Plan,   3 


0|    I    I    I    I    I    I    I  Bl,.„.an.   S 


1 iBIwSTT 


if 


Pixel  appears 
in  COLOR  05 


mr 


Visible 
screen 


Color  selection 
Color  palette  registers  0-31  (COLOR00  to  COLOR31)  are  write-only: 


Register  addr. 

Color  palette  register 

$180 

COLOR00 

$182 

COLOR01 

etc. 

$1BE 

COLOR31 
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Structure  of  a  table  element: 


Bit: 
COLORxx: 

15      14      13      12      11      10     9 
x        x        x        x        R3     R2     R1 

8       7       6       5       4       3        2        1 
R0     G3     G2     G1     GO     B3     B2     B1 

0 
BO 

R0-R3 
G0-G3 
B0-B3 

4-bit  value  for  the  red  component 
4-bit  value  for  the  green  component 
4-bit  value  for  the  blue  component 

The  four  bits  labeled  "x"  are  not  used. 

The  value  obtained  from  the  bit-planes  is  used  as  a  pointer  to  a  table 
element.  Since  there  are  only  32  of  these  color  table  registers,  a  maximum 
of  five  bit-planes  can  be  combined  in  this  mode.  The  bit  from  the  lowest- 
numbered  bit-plane  supplies  the  LSB  of  the  table  entry.  The  bit  from  the 
highest-numbered  bit-plane  supplies  the  MSB. 

This  method  of  obtaining  the  color  from  a  table  allows  a  maximum  of  32 
colors  in  a  picture,  but  these  colors  can  be  selected  from  a  total  of  4096. 
In  high-resolution  mode  only  four  planes  can  be  active  at  one  time  (16 
colors  is  the  limit).  In  this  display  mode  it  doesn't  matter  how  many  planes 
are  combined.  Some  registers  may  simply  remain  unused: 


Number  of  bit-planes      Colors 


1 
2 
3 
4 
5 


2 

4 

8 

16 

32 


Color  registers  used 


COLOR00 
COLOR00 
COLOR00 
COLOR00 
COLOR00 


COLOR01 
COLOR03 
COLOR07 
COLOR15 
COLOR31 


The  extra  half-bright  mode 

In  low-resolution  mode  a  maximum  of  six  bit-planes  can  be  used.  This 
yields  a  range  of  values  of  2^  or  0  to  63.  However,  there  are  only  32 
color  registers  available.  The  extra  half-bright  mode  uses  a  special 
technique  to  get  around  this.  The  lower  five  bits  (bits  0  to  4  from  planes  1 
to  5)  are  used  as  the  pointer  to  a  color  register.  The  contents  of  this  color 
register  is  output  directly  to  the  screen  if  bit  5  (from  bit-plane  6)  is  0.  If 
this  bit  is  1,  each  component  of  the  color  value  is  divided  by  2  before 
being  sent  to  the  screen. 

Dividing  by  2  means  that  the  bits  of  the  three  color  components  are 
shifted  one  bit  to  the  right,  which  amounts  to  a  binary  halving.  The 
intensity  of  each  component  is  then  only  half  as  great,  but  the 
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proportions  of  the  three  components  remains  constant.  The  same  color 
will  be  displayed  on  the  screen,  but  only  half  as  bright. 


Example: 


Bitno.:  5  43210 

Value  from  bit-plane:        10  010  0 


Yields  table  entry  no.  8  (binary  01000  is  8),  COLOR08  contains  the 
following  value  (color:  orange): 


R3 
1 

R2      Rl       R0      G3       G2      Gl       GO 
110         0         110 

B3 
0 

B2 
0 

Bl 

0 

BO 
1 

Since  bit  5  =  1,  the  values  are  shifted  by  1  bit: 

R3 

0 

R2      Rl       RO      G3       G2      Gl       GO 
1110         0         11 

B3 
0 

B2 
0 

Bl 
0 

BO 

0 

This  value  still  corresponds  to  orange,  but  now  it's  only  half  as  bright.  By 
selecting  appropriate  color  values  for  the  32  registers,  it  is  possible  for 
each  pixel  to  take  on  one  of  64  possible  colors  in  the  extra  half-bright 
mode.  The  color  registers  store  the  bright  colors,  which  can  then  be 
dimmed  by  setting  bit  5. 

The  hold-and-modify  mode 

This  mode  allows  the  display  of  all  4096  colors  in  one  picture.  Like  the 
extra  half-bright  mode,  it  is  possible  only  at  low-resolution,  since  all  six 
bit-planes  are  required.  In  this  mode  the  colors  in  a  normal  picture  seldom 
make  extreme  changes  from  pixel  to  pixel.  Usually  smooth  transitions 
from  bright  to  dark  or  dark  to  bright  are  needed. 

In  the  hold-and-modify  mode,  called  HAM  for  short,  the  color  of  the 
previous  pixel  is  modified  by  the  one  that  follows  it.  This  is  responsible 
for  the  fine  gradations  of  shading  that  can  be  achieved  (e.g.,  by 
incrementing  the  blue  component  by  one  step  with  each  successive 
pixel).  The  limitation  is  that  only  one  component  can  change  at  a  time 
(i.e.,  only  the  red,  blue  or  green  intensity  can  be  affected  from  one  pixel 
to  the  next).  To  get  a  smooth  transition  from  dark  to  light,  all  three  color 
components  must  change  for  many  color  mixes.  In  the  HAM  mode  this 
can  be  accomplished  only  by  setting  one  of  the  components  to  the 
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desired  value  at  each  pixel.  This  requires  three  pixels.  By  comparison,  the 
color  of  a  pixel  can  also  be  changed  directly  by  fetching  one  of  16  colors 
from  the  color  table.  How  is  the  value  from  the  bit-planes  interpreted  in 
HAM  mode? 

The  upper  two  bits  (bits  4  and  5  from  bit-planes  5  and  6)  determine  the 
use  of  the  lower  four  bits  (bit-planes  1  to  4).  If  bits  4  and  5  are  0,  the 
remaining  four  bits  are  used  as  a  pointer  to  one  of  the  color  palette 
registers  as  usual.  This  allows  16  colors  to  be  selected  directly.  With  a 
non-zero  combination  of  bits  4  and  5,  the  color  of  the  last  pixel  (to  the 
left  of  the  current  one)  is  taken,  two  of  the  three  color  components  are 
held  constant,  while  the  third  is  replaced  by  the  lower  four  bits  of  the 
current  pixel.  The  top  two  bits  select  the  component  to  be  changed.  This 
sounds  more  complicated  than  it  is.  The  following  table  explains  the  use 
of  the  various  bit  combinations: 


Bit  no.: 

5               4        3 

2 

1 

0 

Function 

0 

0 

C3 

C2 

C1 

CO 

Bits  CO  to  C3  are  used  as  a  pointer  to  one  of  the  color 
registers  in  the  range  of  COLOR00  to  COLOR15.  This 
is  identical  to  normal  color  selection. 

0 

1 

B3 

B2 

B1 

BO 

The  red  and  green  values  of  the  last  (left)  pixel  are  used 
for  the  current  pixel.  The  old  blue  value  is  replaced  by 
the  value  in  BO  to  B3. 

1 

0 

R3 

R2 

R1 

RO 

The  blue  and  green  values  of  the  last  pixel  are  used  for 
the  current  pixel.  The  old  red  value  is  replaced  by  the 
value  in  RO  to  R3. 

1 

1 

G3 

G2 

G1 

GO 

The  blue  and  red  values  of  the  last  pixel  are  used  for  the 
current  pixel  The  old  green  value  is  replaced  by  the 
value  in  GO  to  G3. 

The  border  color  (COLOR00)  is  used  as  the  color  of  the  previous  pixel 
for  the  first  pixel  on  a  line. 

The  dual  playfield  mode 

The  previously  described  modes  use  only  one  playfield.  The  dual 
playfield  mode  allows  two  completely  independent  playfields  to  be 
displayed  simultaneously.  It's  as  though  there  are  two  screens 
superimposed  on  each  other  on  the  same  monitor.  They  can  (almost)  be 
used  completely  independently  of  each  other. 

This  is  especially  interesting  for  games.  For  example,  a  telescope  effect 
can  be  produced  very  easily.  The  front  playfield  is  filled  with  black 
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pixels;  all  except  for  a  hole  in  the  middle  through  a  section  of  the  second 
playfield  can  be  seen. 


Each  of  the  two  playfields  gets  half  the  active  bit-planes  for  its  display. 
Playfield  1  is  formed  from  the  odd  planes,  playfield  2  from  the  even  ones. 
If  an  odd  number  of  bit-planes  is  being  used,  playfield  1  has  one  more 
available  to  it  than  playfield  2. 


2nd  color  choice  in  Dual  Playfield  mode 

...     ,         _._.,_„    ,  Color  table 

Value  from  odd  bit-plane  ICOLOH  00 1 

ra o •*    ~~ 


Playfield  1  color 
from  COLOR  01 


Playfield  2 
color  from 
COLOR  11 


Priority  switch:  H 
no  transparent 
playfield  exists, 
the  color  with 
the  highest 
priority  Is 
displayed 


The  dual  playfield  principle 

The  color  selection  in  dual  playfield  mode  is  performed  as  usual:  The 
value  belonging  to  a  pixel  from  all  the  odd  bit-planes  (playfield  1)  or  all 
the  even  planes  (playfield  2)  is  used  as  a  pointer  to  an  entry  in  the  color 
table.  Since  each  playfield  can  consist  of  a  maximum  of  three  planes,  a 
maximum  of  eight  colors  are  possible.  For  playfield  1,  the  lower  eight 
entries  of  the  color  table  are  used  (COLOR00  to  COLOR07).  For 
playfield  2,  an  offset  of  8  is  added  to  the  value  from  the  bit-planes,  which 
puts  its  colors  in  positions  8  to  15  (COLOR08  to  COLOR15). 

If  a  pixel  has  a  value  of  0,  it  is  made  transparent.  This  means  that  screen 
elements  lying  behind  it  can  be  seen.  This  can  be  the  other  playfield, 
sprites  or  simply  the  background  (COLOR00). 

The  dual  playfield  mode  can  also  be  used  in  the  high-resolution  mode. 
Each  playfield  has  only  four  colors  in  this  mode.  The  division  of  the  color 
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registers  doesn't  change,  but  the  upper  four  registers  of  each  playfield  are 
unused  (playfield  1:  COLOR04  to  07,  playfield  2:  COLOR12  to  15). 


Division  of  the  bit-planes  in  dual  playfield  mode: 


Bit-planes 

Planes  in  playfield  1 

Planes  in  playfield  2 

1 

Plane  1 

none 

2 

Plane  1 

Plane  2 

3 

Planes  1  and  3 

Plane  2 

4 

Planes  1  and  3 

Planes  2  and  4 

5 

Planes  1,3  and  5 

Planes  2  and  4 

6 

Planes  1 , 3  and  5 

Planes  2, 4  and  6 

Color  selection  in  dual  playfield  mode: 


Playfield  1 

Playfield  2 

Planes  5,  3 

1        Color  reg. 

Planes  6, 

4, 2       Color  reg. 

000 

Transparent 

000 

Transparent 

001 

COLOR01 

001 

COLOR09 

01  0 

COLOR02 

010 

COLOR10 

01  1 

COLOR03 

01  1 

COLOR11 

100 

COLOR04 

1  00 

COLOR12 

101 

COLOR05 

101 

COLOR13 

1  1  0 

COLOR06 

1  1  0 

COLOR14 

1  1  1 

COLOR07 

1  1  1 

COLOR15 

Construction  of  the  playfields 

As  previously  mentioned,  a  playfield  consists  of  a  given  number  of 
bit-planes.  What  do  these  bit-planes  look  like?  We  said  earlier  that  they 
were  conceived  as  continuous  areas  of  memory,  in  which  a  screen  line 
was  represented  by  a  number  of  words  depending  on  the  screen  width. 
In  the  normal  case  this  is  20  words  for  low  resolution  (320  pixels  divided 
by  16  pixels  per  word)  and  40  (640/16)  for  high  resolution. 

The  following  steps  are  needed  to  determine  the  exact  construction  of 
the  playfield: 


Define  the  desired  screen  size 

Set  the  bit-plane  size 

Select  the  number  of  bit-planes 

Initialize  the  color  table 

Set  the  desired  mode  (hi-res,  lo-res,  HAM,  etc.) 
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•  Construct  the  Copper  list 

•  Initialize  the  Copper 

•  Activate  the  Copper  and  bit-plane  DMA 

Setting  the  screen  size 

The  Amiga  allows  the  upper  left  corner  and  the  lower  right  corner  of  the 
visible  area  of  the  playfields  to  be  set  anywhere.  This  allows  the  picture 
position  and  size  to  be  varied.  The  resolution  is  one  raster  line  vertically 
and  one  low-resolution  pixel  horizontally.  Two  registers  contain  the 
values.  DIWSTRT  (Display  Window  STaRT)  sets  the  horizontal  and 
vertical  start  positions  of  the  screen  window  (i.e.,  the  line  and  column 
where  the  display  of  the  playfield  begins). 

DIWSTOP  (Display  Window  STOP)  contains  the  end  position  +  1.  This 
refers  to  the  first  line/column  after  the  playfield.  If  the  playfield  extends 
up  to  250  lines,  251  must  be  given  as  the  DIWSTOP  value. 

The  border  color  is  displayed  outside  the  visible  area  (this  corresponds  to 
the  background  color  and  comes  from  the  COLOR00  register). 

DIWSTRT  $08E  (write-only) 


Bit  no.:      1514131211109       8       7       6       5       4       3       2       1       0 
V7    V6    V5    V4    V3    V2    V1     VO     H7    H6    H5    H4    H3    H2    H1     HO 


DIWSTOP  $90  (write-only) 


Bitno.:   15  14  13  12  1 1  10  9   8   7   6   5   4   3   2   1   0 
V7  V6  V5  V4  V3  V2  V1  VO  H7  H6  H5  H4  H3  H2  H1  HO 


The  start  position  stored  in  DIWSTRT  is  limited  to  the  upper  left  quadrant 
of  the  screen,  lines  and  columns  0  to  255,  since  the  missing  MSB's,  V8 
and  H8,  are  assumed  to  be  0.  The  same  applies  to  the  horizontal  end 
position,  only  here  H8  is  assumed  to  be  1,  which  places  it  in  the  range  of 
column  256  to  458.  A  different  method  is  used  for  the  vertical  end 
position.  Positions  less  and  greater  than  row  256  should  be  possible.  The 
MSB  of  the  vertical  end  position,  V8,  is  created  by  inverting  the  V7  bit. 
This  makes  an  end  position  in  the  range  of  lines  128  to  312  possible.  For 
end  positions  from  256  to  312,  you  set  V7  to  0  and  V8  to  1.  If  V7  is  1,  V8 
will  be  0,  indicating  a  position  between  128  and  255. 
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The  normal  screen  window  has  an  upper  left  comer  position  of 
horizontal  129  and  vertical  41  (129,41)  and  a  lower  right  corner  position 
of  448,296.  DIWSTOP  must  be  set  at  449,297.  The  corresponding 
hexadecimal  values  for  DIWSTRT  and  DIWSTOP  are  $2981  and  $29C1. 
With  these  values  the  normal  Amiga  screen  of  640  by  256  pixels  (or  320 
by  256)  is  centered  in  the  middle  of  the  monitor. 

Why  isn't  the  whole  screen  area  used?  There  are  several  reasons  for  this. 
First,  a  normal  monitor  does  not  display  the  entire  picture.  Its  visible 
range  normally  begins  a  few  columns  or  lines  after  the  blanking  gap.  In 
addition,  a  picture  tube  is  not  rectangular.  If  the  screen  window  was  set 
as  high  and  wide  as  the  monitor  tube,  the  corners  of  the  tube  would  hide 
part  of  the  picture. 

Another  limitation  on  the  DIWSTRT  and  DIWSTOP  values  is  imposed  by 
the  blanking  gaps.  The  vertical  gap  is  in  the  range  of  lines  0  to  25.  This 
limits  the  visible  vertical  area  to  lines  26  to  312  ($1A  to  $138).  The 
horizontal  blanking  gap  lies  between  columns  30  to  106  ($1E  to  $6A). 
Visible  horizontal  positions  begin  at  column  107  ($6B). 

After  the  position  of  the  screen  window  has  been  set,  the  start  and  end  of 
the  bit-plane  DMA  must  be  set  as  well.  Proper  timing  of  the  reading  of 
data  from  the  bit-planes  is  required  to  ensure  that  the  pixels  will  appear  at 
the  desired  time  on  the  screen.  Vertically,  this  isn't  a  problem.  Screen 
DMA  begins  and  ends  in  the  lines  established  by  DIWSTRT  and 
DIWSTOP  as  the  boundaries  of  the  screen  window. 

Horizontally,  it  is  somewhat  more  complicated.  In  order  for  a  pixel  to  be 
displayed  on  the  screen,  the  current  words  of  all  bit-planes  are  required 
by  the  electronics.  For  six  bit-planes  in  low  resolution,  this  takes  eight 
bus  cycles.  For  high  resolution,  four  cycles  are  required.  (Remember:  In 
one  bus  cycle,  two  low-resolution  or  four  high-resolution  pixels  are 
displayed.) 

In  addition,  the  hardware  needs  a  half  bus  cycle  before  the  data  can 
appear  on  the  screen.  Therefore,  the  bit-plane  DMA  must  begin  exactly 
8.5  cycles  (17  pixels)  before  the  start  of  the  screen  window  (4.5  cycles  or 
9  pixels  in  high  resolution). 
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The  bus  cycle  of  the  first  bit-plane  DMA  in  the  line  is  stored  in  the 
DDFSTRT  (Display  Data  Fetch  STaRT)  register,  and  that  of  the  last  in 
DFFSTOP  (Display  Data  Fetch  STOP): 

DDFSTRT  $092  (write-only),  DDFSTOP  $094  (write-only) 


Bit  no.:         15     13     12     11     10     9       8       7       6       5       4       3       2       1       0 
Function:    x       x       x      x       x       x       x       H8    H7    H6    H5    H4    H3    x       x 


The  resolution  is  eight  bus  cycles  in  lo-res  mode  (with  H3  always  0)  and 
four  in  hi-res  mode.  H3  serves  as  the  lowest  bit.  The  reason  for  the  limited 
resolution  lies  in  the  division  of  the  bit-plane  DMA.  In  lo-res  mode,  each 
bit-plane  is  read  once  every  eight  bus  cycles,  so  the  DDFSTRT  value 
must  be  an  integral  multiple  of  eight  (HI  to  H3  =  0).  The  same  applies  to 
hi-res  mode,  except  that  the  bit-planes  are  read  every  four  bus  cycles  (HI 
and  H2  =  0).  Regardless  of  the  resolution,  the  difference  between 
DIWSTRT  and  DIWSTOP  must  always  be  divisible  by  eight,  since  the 
hardware  always  divides  the  lines  into  sections  of  eight  bus  cycles.  Even 
in  hi-res  mode  the  bit-plane  DMA  is  performed  for  eight  bus  cycles 
beyond  DIWSTOP,  so  that  32  points  are  always  read. 

The  correct  values  for  DIWSTRT  and  DIWSTOP  are  calculated  as 
follows: 

Calculation  of  DDFSTRT  and  DDFSTOP  in  lo-res  mode: 


HStart  =  Horizontal  start  of  screen  window 
DDFSTRT  =  (HStart/2  -  8.5)  AND  $FFF8 
DDFSTOP  =  DDFSTRT  +  (pixels  per  line/2  -  8) 


For  HStart  =  $81  and  320  pixels  per  line  this  gives: 


DDFSTRT  =  ($81/2  -  8.5)  AND  $FFF8  =  $38 
DDFSTOP  =  $38  +  (320/2  -  8)  =  $D0 


Calculation  of  DDFSTRT  and  DDFSTOP  in  hi-res  mode: 


DDFSTRT  =  (HStart/2  -  4.5)  AND  $FFFC 
DDFSTOP  =  DDFSTRT  +  (pixels  per  line/4  -  8) 
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For  HStart  =  $81  and  640  pixels  per  line  this  gives: 


DDFSTRT  =  (S81/2  -  4.5)  AND  $FFFC  =  $3C 
DDFSTOP  =  $3C  +  (640/4  -  8)  =  $D4 


DDFSTRT  may  not  be  less  than  $18  and  DDFSTOP  may  not  be  greater 
than  $D8.  A  DDFSTRT  value  less  than  $28  does  not  make  sense,  since 
pixels  would  then  have  to  be  displayed  during  the  horizontal  blanking 
gap,  which  is  not  possible  (except  in  scrolling).  Since  the  DMA  cycles  of 
bit-planes  and  sprites  overlap  with  DDFSTRT  positions  less  than  $34, 
some  sprites  may  not  be  visible,  depending  on  the  value  of  DDFSTRT. 

Moving  the  screen  window 

If  you  want  to  move  the  screen  window  horizontally  by  using  DIWSTRT 
and  STOP,  it  may  occur  that  the  difference  between  DIWSTRT  and 
DDFSTRT  is  not  exacdy  8.5  bus  cycles  (17  pixels),  since  DFFSTRT  can 
only  be  set  in  steps  of  eight  bus  cycles.  In  such  a  case,  a  part  of  the  first 
data  word  would  disappear  into  the  invisible  area  to  the  left  of  the  screen 
window.  To  prevent  this,  it  is  possible  to  shift  the  data  to  the  right  before 
sending  it  to  the  screen,  so  that  it  matches  the  start  of  the  screen  window. 
The  section  on  scrolling  explains  how  this  is  done. 

Setting  bit-map  addresses 

The  values  in  DDFSTRT  and  DDFSTOP  determine  how  many  data  words 
are  displayed  per  line.  The  start  address  must  now  be  set  for  each  bit-map 
so  that  the  DMA  controller  can  find  pixel  data.  Twelve  registers  contain 
these  addresses.  A  pair  of  registers,  BPLxPTH  and  BPLxPTL,  is  used  for 
each  bit-plane.  Together  they  are  referred  to  as  simply  BPLxPT  (Bit- 
plane  x  Pointer). 
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Addr. 

Name 

Function 

$0E0 

BPL1PTH 

Start  address  of 

Bits  16-20 

$0E2 

BPL1PTL 

bit-plane  1 

Bits  0-15 

$0E4 

BPL2PTH 

Start  address  of 

Bits  16-20 

$0E6 

BPL2PTL 

bit-plane  2 

Bits  0-15 

$0E8 

BPL3PTH 

Start  address  of 

Bits  16-20 

$OEA 

BPL3PTL 

bit-plane  3 

Bits  0-15 

$OEC 

BPL4PTH 

Start  address  of 

Bits  16-20 

$OEE 

BPL4PTL 

bit-plane  4 

Bits  0-15 

$0F0 

BPL5PTH 

Start  address  of 

Bits  16-20 

$0F2 

BPL5PTL 

bit-plane  5 

Bits  0-15 

$0F4 

BPL6PTH 

Start  address  of 

Bits  16-20 

$0F6 

BPL6PTL 

bit-plane  6 

Bits  0-15 

The  DMA  controller  does  the  following  when  displaying  a  bit-plane:  The 
bit-plane  DMA  remains  inactive  until  the  first  line  of  the  screen  window 
is  reached  (DIWSTRT).  Now  it  gets  the  data  words  from  the  various  bit- 
planes  at  the  column  stored  in  DFFSTRT.  It  uses  BPLxPT  as  a  pointer  to 
the  data  in  the  chip  RAM.  After  each  data  word  is  read,  BPLxPT  is 
incremented  by  one  word.  The  words  read  go  to  the  BPLxDAT  registers. 
These  registers  are  used  only  by  the  DMA  channel.  When  all  six 
BPLxDAT  registers  have  been  provided  with  the  corresponding  data 
words  from  the  bit-planes,  the  data  goes  bit  by  bit  to  the  video  logic  in 
Denise,  which  selects  one  of  the  4096  colors,  depending  on  the  color 
mode  chosen,  and  then  outputs  this  to  the  screen. 

When  DFFSTOP  is  reached,  the  bit-plane  DMA  pauses  until  DFFSTRT 
for  the  next  line,  then  the  process  is  repeated  until  the  last  line  of  the 
screen  window  (DIWSTOP)  is  displayed. 

The  BPLxPT  now  points  to  the  first  word  after  the  bit-plane.  But  since 
the  BPLxPT  should  point  to  the  first  word  in  the  bit-plane  by  the  next 
picture,  it  must  be  set  back  to  this  value.  The  Copper  takes  care  of  this 
quickly  and  easily.  A  simple  Copper  list  for  a  playfield  with  four  bit- 
planes  looks  like  this: 


AddrPlanexH  =  Address  of  bitplane  x, 
AddrPlanexL  =  Address  of  bitplane  x, 
MOVE  #AddrPlanelH,BPLlPTH 
MOVE  #AddrPlanelL,BPLlPTL 
MOVE  #AddrPlane2H,BPL2PTH 
MOVE  #AddrPlane2L,BPL2PTL 
MOVE  #AddrPlane3H,BPL3PTH 
MOVE  #AddrPlane3L,BPL3PTL 


bits  16-20 
bits  0-15 
initialize  pointer  to  bitplane 

initialize  pointer  to  bitplane 

initialize  pointer  to  bitplane 
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MOVE  #AddrPlane4H,BPL4PTH 
MOVE  #AddrPlane4L, BPL4PTL 
WAIT  ($FF,$FE) 


; initialize  pointer  to  bitplane  4 

;End  of  Copper  list  (wait  for 
.•impossible  screen  position) 


Resetting  the  BPLxPT  is  absolutely  necessary.  If  you  don't  use  a  Copper 
list,  this  must  be  done  by  the  processor  in  the  vertical  blanking  interrupt. 

Scrolling  and  extra-large  playfields 

The  previous  playfields  were  always  the  same  size  as  the  screen. 
However,  it  would  often  be  useful  to  have  a  large  playfield  in  memory, 
not  all  of  which  is  visible  on  the  screen  at  one  time,  but  which  can  be 
smoothly  scrolled  in  all  directions.  This  is  easily  done  on  the  Amiga.  The 
following  sections  illustrate  this  in  both  the  X  and  Y  directions. 


Bit-plane 

-  Width :40  words;  height:  400  lines 

n 

n+2 

n+4 

n+78 

n+80 

n+82 

n+84 

n+158 

n+160 

n+162 

n+164 

n+166     S                              |n+202 

n+238 

BPL*PT=n+164 

Modulo=40  bytes  (20  words) 

Visible  screen  area: 
Width :20  words;  height:  200  lines 

BPL*PT+80 
moves  the 
visible  screen 
area  1  line 
down 

n+16080|n+16082 

n+16084|                           |n+16122| 

A  scroll  value  from  0  to  1 5  moves  the 
visible  screen  area  0  to  1 5  pixels  to  the  left 

BPL*PT+2  moves  the  visible  screen  area  1  word  to 

the  right 

n+31920 

n+31998 

n^Starting  address  of  the  bit-plane        Total  size  of  bit-plane:  32,000  bytes 


Scrolling 

Extra-tall  playfields  and  vertical  scrolling 

Vertical  scrolling  is  very  easy  to  do.  The  necessary  bit-planes  are  placed 
in  memory  as  usual,  but  this  time  they  contain  more  lines  than  the  screen. 
With  a  standard  window  height  of  256  lines,  for  example,  a  double- 
height  playfield  is  simply  512  lines  in  memory.  In  order  to  move  the 
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screen  window  smoothly  over  this  extra-tall  playfield,  you  change  the 
values  of  BPLxPT.  If  you  want  the  screen  window  to  show  lines  100  to 
356,  the  BPLxPT  pointer  must  be  set  to  the  first  word  of  the  100th  line. 
With  a  screen  width  of  320  pixels,  each  line  occupies  20  words  (40 
bytes)  in  memory.  Multiplying  by  100  lines  gives  an  address  of  4000. 
Add  this  to  the  starting  address  of  the  playfield,  and  you  have  the  desired 
value  for  BPLxPT.  To  scroll  the  playfield  in  the  screen  window,  simply 
change  this  value  by  one  or  more  lines  with  each  picture,  depending  on 
the  scroll  speed  desired.  Since  the  BPLxPT  can  only  be  changed  outside 
the  visible  area,  a  Copper  list  is  used.  You  can  change  the  values  in  the 
Copper  list,  and  the  Copper  automatically  writes  them  to  the  BPLxPT 
registers  at  the  right  time.  You  just  have  to  be  careful  not  to  change  the 
Copper  list  while  the  Copper  is  accessing  its  commands.  Otherwise  the 
processor  might  change  one  word  of  the  address  while  the  Copper  is 
reading  it  and  the  Copper  gets  the  wrong  address. 

Extra-wide  playfields  and  horizontal  scrolling 

Special  registers  exist  for  horizontal  scrolling  and  extra-wide  playfields 
(all  write-only): 


$108      BPL1MOD      Modulo  value  for  the  odd  bit-planes 
$10A     BPL2MOD      Modulo  value  for  the  even  bit-planes 


BPLCON1  $102 


Bit  no:  15-8  7  6  5  4  3  2  1  0 

Function:  Unused      P2H3      P2H2      P2H1       P2H0      P1H3      P1H2      P1H1       P1H0 

P1  HO  -  P1 H3  Position  of  the  even  planes  (four  bits) 

P2H0  -  P2H3  Position  of  the  odd  planes  (four  bits) 


The  modulo  values  from  the  BPLxMOD  registers  allow  (so  to  speak) 
rectangular  memory  areas.  This  principle  is  used  often  in  the  Amiga 
hardware.  Inside  a  large  memory  area,  which  is  divided  into  rows  and 
columns,  a  smaller  area  of  specified  height  and  width  can  be  defined. 
Let's  say  that  the  large  memory  area,  in  this  case  our  playfield,  is  640 
pixels  wide  and  256  high.  This  gives  us  256  lines  of  40  words  (80  bytes) 
each.  The  smaller  area  corresponds  to  the  screen  window  and  has  the 
normal  size  of  320  x  200  pixels,  or  only  20  words  per  line.  The  problem  is 
that  when  a  line  is  output,  BPLxPT  is  incremented  by  20  words.  But  in 
order  to  get  the  next  line  of  your  playfield,  it  must  be  incremented  by  40 
words.  After  each  line,  another  20  words  must  be  added  to  BPLxPT.  The 
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Amiga  can  take  care  of  this  automatically.  The  difference  between  the 
two  different  line  lengths  is  written  into  the  modulo-register.  After  a  line 
is  output,  this  value  is  automatically  added  to  the  BPLxPT. 

Width  of  playfield:  80  bytes  (40  words). 

•  Width  of  screen  window:  40  bytes  (20  words). 

•  Modulo  value  needed:  40  bytes  (The  modulo  value  must  always  be 
an  even  number  of  bytes). 

•  Start  =  start  address  of  the  first  line  of  the  playfield. 
Output  of  the  1st  line: 


Word:  0  1  2  3  ...        19 

BPLxPT:      Start       Start+2    Start+4    Start+6    ...       Start+38 


After  the  last  word  is  output,  BPLxPT  is  incremented  by  1  word: 

BPLxPT  =  Start+4 0 

After  the  end  of  the  line,  the  modulo  value  is  added  to  BPLxPT: 

BPLxPT  =  BPLxPT  +  modulo  BPLxPT  =  Start+40  +  40  =  Start+80 

Output  of  the  2nd  line: 


Word:  0  12  3  ...         19 

BPLxPT:      Start+80     Start+82     Start+84    Start+86     ...         Start+118 


This  example  shows  the  left  half  of  the  large  bit-map  being  displayed  in 
the  screen  window.  To  start  at  a  different  horizontal  position,  simply  add 
the  desired  number  of  words  to  the  start  value  of  BPLxPT  and  keep  the 
modulo  value  the  same. 

The  initial  values  are  as  previously  shown.  The  only  difference  is  that 
BPLxPT  is  not  at  Start,  but  at  Start+40,  so  the  right  half  of  the  large 
playfield  is  displayed. 
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Output  of  the  1st  line: 


Word:  0  1  2  3  ...         19 

BPLxPT:      Start+40    Start+42    Start+44    Start+46    ...        Start+78 


After  the  last  word  is  output: 


BPLxPT  =  Start+80 


Now  the  modulo  value  is  added  to  BPLxPT: 

BPLxPT  =  BPLxPT+modulo  BPLxPT  =  Start+80  +  40  =  Start+120 

Output  of  the  2nd  line: 


Word:  0  1  2  3  ...      19 

BPLxPT:     Start+120     Start+122    Start+124    Start+126    ...      Start+158 


Separate  modulo  values  can  be  set  for  the  odd  and  even  bit-planes.  This 
allows  two  different  sized  playfields  in  the  dual-playfield  mode. 

If  this  mode  is  not  being  used,  set  both  BPLxMOD  registers  to  the  same 
modulo  value. 

The  screen  can  be  moved  horizontally  in  steps  of  16  pixels  with  the 
BPLxPT  and  BPLxMOD  registers.  Fine  scrolling  in  single  pixel  steps  is 
possible  with  the  BPLCON1  register.  The  lower  four  bits  contain  the 
scroll  value  for  the  even  planes,  bits  4  to  7  for  the  odd  planes.  This  scroll 
value  delays  the  output  of  the  pixel  data  read  for  the  corresponding 
planes.  If  it  is  zero,  the  data  is  output  exactly  8.5  (in  hi-res,  4.5)  bus 
cycles  after  the  DDFSTRT  position;  otherwise  it  appears  up  to  15  pixels 
later,  depending  on  the  scroll  value.  So,  the  picture  is  shifted  to  the  right 
within  the  screen  window  by  the  value  in  BPLCON1. 

Smooth  scrolling  of  the  screen  contents  to  the  right  can  be  accomplished 
by  incrementing  the  value  of  BPLCON1  from  0  to  15  and  then  setting  it 
back  to  0  while  decrementing  the  BPLxPT  by  one  word  as  previously 
described. 

Left  scrolling  can  be  accomplished  by  decrementing  the  scroll  value  from 
15  to  0  and  then  incrementing  BPLxPT  by  one  word.  BPLCON1  should 
be  changed  only  outside  the  visible  area.  This  can  be  done  during  the 
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vertical  blanking  interrupt  or  the  Copper  can  be  used.  The  value  in  the 
Copper  list  can  be  changed  at  any  time  and  will  be  written  to  the 
BPLCON1  register  during  the  vertical  blanking  gap. 

When  the  BPLCON1  value  is  used  to  shift  the  picture  to  the  right,  excess 
pixels  on  the  left  are  correctly  eliminated  from  view,  but  no  new  ones  can 
appear  on  the  right  until  new  pixel  data  has  been  read.  To  do  this,  the 
DDFSTRT  value  must  be  set  ahead  of  its  normal  start  by  8  bus  cycles  (4 
cycles  in  hi-res).  The  DDFSTRT  value  is  calculated  as  usual  from  the 
desired  screen  window  and  then  decremented  by  8  (or  4).  From  the 
normal  DDFSTRT  value  of  $38  we  get  $30  (sprite  7  is  lost).  The  extra 
word  read  is  normally  not  visible.  But  when  the  scroll  value  is  other  than 
zero,  its  pixels  appear  in  the  free  positions  at  the  left  edge  of  the  screen 
window.  If  the  window  is  320  pixels  wide,  21,  instead  of  the  usual  20, 
data  words  are  now  read  per  line.  This  must  be  considered  when 
calculating  the  bit-planes  and  modulo  values. 

The  screen  window  can  also  be  placed  at  any  desired  horizontal  position 
by  using  the  scroll  value.  If  the  difference  between  DIWSTRT  and 
DFFSTRT  is  more  than  17  pixels,  you  simply  shift  the  read  data  to  the 
right  by  the  amount  over  17. 

The  interlace  mode 

Although  the  interlace  mode  doubles  the  number  of  displayable  lines,  its 
programming  technique  differs  from  that  of  the  normal  display  mode  only 
by  a  different  modulo  value  and  a  new  Copper  list.  As  explained  earlier, 
in  interlace  mode  the  odd  and  even  lines  are  displayed  in  alternate 
pictures.  To  allow  an  interlace  playfield  to  be  represented  normally  in 
memory,  the  modulo  value  is  set  equal  to  the  number  of  words  per  line. 
After  a  line  is  output,  the  length  of  a  line  is  added  again  to  BPLxPT, 
which  amounts  to  skipping  over  the  next  line.  In  each  picture  only  every 
other  line  is  displayed.  Now  the  BPLxPT  only  needs  to  be  set  to  the  first 
or  second  line  of  the  playfield,  depending  on  the  frame  type,  so  that  only 
the  even  or  the  odd  lines  will  be  shown.  In  a  long  frame  BPLxPT  is  set  to 
line  1  (odd  lines  only);  in  a  short  frame  it  is  set  to  line  2  (even  lines  only). 
The  Copper  list  for  an  interlace  playfield  is  somewhat  more  complicated, 
because  two  lists  are  needed.  There  is  one  for  each  frame  type,  so  for 
each  picture,  we  alternate  between  them: 
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Copper  list  for  an  interlaced  playfield: 

Linel  =  address  of  first  line  of  bitplane. 
Line2  =  address  of  second  line  of  bitplane. 

Copper  1: 

MOVE  #LinelHi , BPLxPTH         ;set  pointer  for  BPLxPT  to  the 
MOVE  #LinelLo,  BPLxPTL         ,-address  of  the  first  line 

; other  Copper  commands 
MOVE  #Copper2Hi , C0P1LCH       ;set  address  of  Copper  list 
MOVE  #Copper2Lo,C0PlLCL       ;to  Copper2 
WAIT  ($FF,$FE)  ;end  of  1st  Copper  list 

Copper2: 

MOVE  #Line2Hi,  BPLxPTH         ,-set  pointer  for  BPLxPT  to  the 
MOVE  #Line2Lo, BPLxPTL         ;address  of  the  second  line 

; other  Copper  commands 
MOVE  #CopperlHi,COPlLCH       ;set  address  of  Copper  list 
MOVE  #CopperlLo,COPlLCL       ;to  Copperl 
WAIT  ($FF,$FE)  ;end  of  2nd  Copper  list 

The  Copper  alternates  its  Copper  list  after  each  frame  by  loading  the 
address  of  the  other  list  into  C0P1LC  at  the  end  of  a  command  list.  This 
address  is  automatically  loaded  into  the  program  counter  of  the  Copper 
at  the  start  of  the  next  frame.  The  interlace  mode  should  be  initialized 
carefully  so  that  the  Copper  list  for  odd  lines  is  actually  processed  within 
a  long  frame: 

Set  COP  1LC  to  Copperl . 

Set  the  LOF-bit  (bit  15)  in  the  VPOS  register  ($2A)  to  0.  This 
ensures  that  the  first  frame,  after  interlace  mode  is  enabled,  is  a  long 
frame  and  therefore  suited  to  Copperl.  The  LOF  bit  is  inverted  with 
each  frame  in  interlace  mode.  If  it  is  set  to  0,  it  changes  to  1  at  the 
start  of  the  next  frame.  The  first  frame  is  sure  to  be  a  long  frame. 

•  Interlace  mode  on. 

•  Wait  for  first  line  of  next  picture  (line  0). 

•  Copper  DMA  on. 

All  other  register  functions  remain  unchanged  in  interlace  mode.  All  line 
specifications  (such  as  in  DIWSTRT)  always  refer  to  the  line  number 
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within  the  current  frame  (0  -  3 1 1  for  a  short  frame  and  0  -  312  for  a  long 
frame).  If  the  interlace  mode  is  enabled  without  changing  other  registers, 
a  faint  flickering  is  noticeable  because  the  lines  of  the  frames  are  now 
displaced  from  each  other,  even  though  both  frames  contain  the  same 
graphics  data.  When  doubly-large  bit-planes  and  the  appropriate  modulo 
values  are  set  up  with  suitable  Copper  lists  so  that  different  data  is 
displayed  in  each  frame,  then  the  desired  doubling  in  the  number  of  lines 
is  noticed. 

The  interlace  mode  now  results  in  a  stronger  flickering  since  each  line  is 
displayed  only  once  every  two  frames,  thus  being  refreshed  25  times  per 
second.  This  flickering  can  be  reduced  to  a  minimum  by  selecting  the 
lowest  possible  contrast  (intensity  difference)  between  colors  displayed. 
It  is  more  difficult  for  the  human  eye  to  distinguish  changes  at  low 
contrast. 

The  control  registers 

There  are  three  control  registers  for  activating  the  various  modes: 
BPLCON0  to  BPLCON2.  BPLCON1  contains  the  scroll  value.  The  other 
two  are  constructed  as  follows: 

BPLCON0  $100 


Bit  no. 

Name 

Function 

15 

HIRES 

High-resolution  mode  on  (HIRES  =  1) 

14 

BPU2 

The  three  BPUx  bits  comprise  a  3-bit  number 

13 

BPU1 

which  contains  the  number 

12 

BPUO 

of  bit-planes  used  (0  to  6). 

11 

HOMOD 

Hold-and-modify  on  (HOMOD  =  1) 

10 

DBPLF 

Dual  playfield  on  (DBPLF  =  1 ) 

9 

COLOR 

Video  output  color  (COLOR  =  1) 

8 

GAUD 

Genlock  audio  on  (GAUD  =  1) 

7 

— 

Unused 

6 

SHRES 

Super  hi-res  on 

5-4 

... 

Unused 

3 

LPEN 

Activate  lightpen  input  (LPEN  =  1) 

2 

LACE 

Interlace  mode  on  (LACE  =  1) 

1 

ERSY 

External  synchronization  on  (ERSY  =  1) 

0 

BPLCON30N 

Bit-plane  control  register  3  on 

HIRES 

The  HIRES  bit  enables  the  high-resolution  display  mode  (hi-res,  640 
pixels/line). 
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BPL0-BPL2 

These  three  bits  form  a  3-bit  number  which  selects  the  number  of  active 
bit-planes.  Only  values  between  0  and  6  are  allowed. 

HOMOD  andDBPLF 

These  two  bits  select  the  corresponding  modes.  They  cannot  both  be 
active  at  the  same  time.  The  extra-half-bright  mode  is  automatically 
activated  when  all  six  bit-planes  are  enabled  and  neither  HOMOD  nor 
DBPLF  is  selected. 

LACE 

When  the  LACE  bit  is  set,  the  LOF-frame  bit  in  the  VPOS  register  is 
inverted  at  the  start  of  each  new  frame,  causing  the  desired  alternation 
between  long  and  short  frames. 

SHRES 

Super-hi-res  mode  is  enabled  with  this  bit.  This  mode  was  introduced 
with  the  new  ECS  custom  chips  of  the  A3000. 

COLOR 

The  COLOR  bit  turns  the  color  burst  output  of  Agnus  on.  Only  when 
Agnus  delivers  this  color  burst  signal  can  the  video  mixer  create  a  color 
video  signal.  Otherwise  it  is  black  and  white.  The  RGB  output  is  not 
affected  by  this. 

ERSY 

The  ERSY  bit  switches  the  connections  for  the  vertical  and  horizontal 
synchronization  signals  from  output  to  input.  This  allows  the  Amiga 
picture  to  be  synchronized  by  external  signals.  The  genlock  interface 
uses  this  bit  to  be  able  to  mix  the  Amiga's  picture  with  another  video 
image.  The  GAUD  bit  is  also  provided  for  the  genlock  interface. 

BPLCON30N 

This  activates  the  new  ECS  chip's  BPLCON3  register. 
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BPLC0N2  $104 


Bit  no.:       15-7     6  5  4  3  2  10 

Function:    Gen.    PF2PRI    PF2P2     PF2P1     PF2P0     PF1P2     PF1P1     PF1P0 


PF2P0-PF2P2  and  PF1P0-PF1P2  determine  the  priority  of  the  sprites  in 
relation  to  the  playfields  (see  the  next  section). 

PF2PRI:  If  this  bit  is  set,  the  even  planes  have  priority  over  (appear 
before)  the  odd  planes.  It  has  a  visible  effect  only  in  dual  playfield  mode. 

Activating  the  screen  display 

The  upper  bits  of  the  BPLCON2  register  contain  more  control  bits  for 
genlock  use. 

After  alfthe  registers  have  been  loaded  with  the  desired  values,  the  DMA 
channel  for  the  bit-planes  must  be  enabled  and,  if  the  Copper  is  used 
(which  is  normally  the  case),  its  DMA  channel  must  also  be  enabled.  The 
following  MOVE  command  accomplishes  this  by  setting  the  DMAEN, 
BPLEN  and  COPEN  bits  in  the  DMA  control  register  DMACON: 


MOVE.W  #$8310,$DFF096 

Sample  programs 

Program  1:  Extra-half-bright  demo 


This  program  creates  a  playfield  with  the  standard  dimensions  320  by 
256  pixels  in  lo-res  mode.  Six  bit-planes  are  used  so  the  extra-half-bright 
mode  is  activated  automatically.  At  the  beginning  the  program  allocates 
the  memory  needed. 

Since  the  addresses  of  the  individual  bit-planes  are  not  known  until  this 
time,  the  Copper  list  is  not  copied  from  the  program,  but  created  directly 
in  the  chip  RAM.  It  contains  only  the  commands  for  setting  the  BPLxPT 
registers. 

To  show  you  something  of  the  64  possible  colors,  the  program  draws 
16x1 6-pixel  blocks  in  all  colors  at  random  positions.  The  VHPOS  register 
is  used  as  a  random-number  generator. 
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;***  Demo  for  the  Extra-Half bright -Mode  *** 

; CustomChip-Register 

INTENA   =  $9A  ; Interrupt-Enable-Register  (write) 

DMACON  =  $96  ;DMA-Control  register  (write) 

COLOR00  =  $180  ;Color  palette  register  0 

VHPOSR  =  $6  ;Ray  position  (read) 

; Copper  Register 


COP1LC  =  $80 
COP2LC  =  $84 
COPJMP1  =  $88 
COPJMP2  =  $8a 


;Address  of  1.  Copperlist 
/Address  of  2.  Copperlist 
;Jump  to  Copperlist  1 
;Junip  to  Copperlist  2 


;Bitplane  Register 


BPLCONO 

= 

$100 

BPLCON1 

= 

$102 

BPLCON2 

= 

$104 

BPL1PTH 

= 

$0E0 

BPL1PTL 

= 

$0E2 

BPL1MOD 

= 

$108 

BPL2MOD 

= 

$10A 

DIWSTRT 

= 

$08E 

DIWSTOP 

= 

$090 

DDFSTRT 

= 

$092 

DDFSTOP 

= 

$094 

;Bitplane  Control  register  0 
;1  (Scrollw  value) 
;2  (SpriteoPlayfield  Priority) 
; Number  of   1.  Bitplane 

;Modulo-Value  for  odd  Bit-Planes 
; ModulO -Value  for  even  Bit-Planes 
/Start  of  the  screen  windows 
;End  of  the  screen  windows 
; Bit -Plane  DMA  Start 
; Bit-Plane  DMA  Stop 


;CIA-A  Port  register  A  (Mouse  key) 

CIAAPRA  =  $bfe001 

;Exec  Library  Base  Offsets 


OpenLibrary  =  -30-522 
Forbid  =  -30-102 
Permit  =  -30-108 
AllocMem  =  -30-168 
FreeMem     =  -30-180 

/graphics  base 

StartList   =  38 


; LibName , Vers  ion/al , dO 


;ByteSize,Requirements/dO,dl 
;MemoryBlock,ByteSize/al,dO 


; other  Labels 
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Execbase 

Planesize 

CLsize 

Chip 

Clear 


=  4 

=  40*200 
=  13*4 
=  2 

=  Chip+$10000 


;Size  of  Bitplane:  40  Bytes  by  200  lines 

;The  Copperlist  with  13  commands 

; Chip-RAM  request 

; clear  previous  Chip-RAM 


;***  Initialize  programm  *** 


Start : 


; Request  memory  for  the  Bitplanes 


move.l  Execbase, a6 
move.l  #Planesize*6,dO 
move.l  #clear,dl 
jsr    AllocMem(a6) 
move .1  dO , Planeadr 
beq    Ende 


/Memory  size  of  all  Planes 

.-Memory  to  be  with  filled  with  nulls 

; Request  memory 

;Address  of  the  first  memory  Plane 

; Error!  ->  Ende 


;Request  memory  for  Copperlist 

moveq   #Clsize,d0  ;Size  of  the  Copperlist 

moveq  ichip, dl 
jsr    AllocMem(a6) 
move .1  dO , CLadr 
beq    FreePlane 


; Build  Copperlist 

moveq  #5,d4 
move .1  dO , aO 
move.l  Planeadr, dl 
move.w  #bpllpth,d3 

MakeCL:  move.w  d3,(a0)+ 
addq.w  #2,d3 
swap   dl 
move.w  dl, (a0)+ 
move.w  d3, (a0)+ 
addq.w  #2,d3 
swap   dl 
move.w  dl, (a0)+ 
add.l  #planesize,dl 

dbf    d4 , MakeCL 

move.l  #$fffffffe, (aO) 


; Error!  ->  Free  RAM  for  Bitplanes 


;6  Planes  =  6  loops  to  run  through 
;Address  of  the  Copperlist  to  aO 

; first  Register  to  d3 

;BPLxPTH  ins  RAM 
;next  Register 

; Hi-word  of  the  Plane  address  in  RAM 
;BPLxPTL  ins  RAM 
/next  Register 

;Lo-word  of  the  Plane  address  in  RAM 
/Address  of  the  next  Plane  calculated 


/End  of  Copperlist 
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;***  Main  programm  *** 

;DMA  and  Task  switching  off 

jsr  forbid (a6) 
lea  $dff000,a5 
move.w  #$03e0,dmacon(a5) 


;Copper  initialization 

move.l  CLadr,copllc(a5) 
clr.w  copjmpl(a5) 

;Color  table  with  different  color  fills 

;Value  for  color  register 

; first  color 


moveq  #31, dO 

lea  color00(a5) ,al 

moveq  #l,dl 
SetTab: 

move.w  dl, (al)+ 

mulu  #3,dl 

dbf  dO , SetTab 


; Color  in  color  register 
/calculate  next  color 


; Standard  value  for 
; screen  window 
;and  BitplaneDMA 


;Playfield  initialization 

move.w  #$3081,diwstrt(a5) 

move.w  #$30cl,diwstop(a5) 

move.w  #$0038,ddfstrt(a5) 

move.w  #$00d0,ddfstop(a5) 

move.w  #%0110001000000000,bplcon0(a5)  ;6  Bitplanes 

clr.w  bplconl(a5)  ;no  Scrolling 

clr.w  bplcon2(a5)  .-Priority  makes  no  difference 

clr.w  bpllmod(a5)  ;Modulo  for  all  Planes  equals  Null 

clr.w  bpl2mod(a5) 


;DMA  on 

move.w  #$8380,dmacon(a5) 

;Bitplane  modification 

moveq  #40,d5 
clr.l  d2 

Loop:   clr.l  dO 
move . w  vhposr (a5 ) , dO 
and.w  #$3ffe,d0 
cmp.w   #$2580, dO 
bcs    Continue 


; Bytes  per  line 

; Begin  with  color  0 


,- Random  value  to  dO 
/Unnecessary  Bits  masked  out 
; Large  as  Plane? 
;When  not  ,  then  continue 
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and.w  #$lffe,dO  ;else  erase  upper  bit 

Continue:  move.l  Planeadr,a4  ; Address  of  the  l.Bitplane  to  a4 

add.l   d0,a4  ; Calculate  address  of  the  Blocks 

moveq  #5,d4  /Number  for  Bitplanes 

move.l  d2,d3  ; Color  in  work  register 


Block: 
clr.l   dl 
lsr    #l,d3 
negx.w  dl 
moveq  #15, dO 
move .1  a4 , a3 


;one  Bit  of  color  number  in  X-Flag 

;use  dl  to  adjust  X-Flag 

;16  lines  per  Block 

; Block  address  in  working  register 


Fill: 
move.w  dl, (a3) 
add.l  d5,a3 
dbf    dO,Fill 


;Word  in  Bitplane 
; compute  next  line 


add.l   #Planesize,a4 
dbf    d4, Block 


;next  Bitplane 


addq.b  #l,d2 
btst   #6,ciaapra 
bne    Loop 


;next  color 

;mouse  key  pressed? 

;no   ->  then  continue 


;***  End  programm  *** 

/Activate  old  Copperlist 

move . 1  #GRname , a 1 

clr.l  dO 

jsr  OpenLibrary (a6) 

move.l  d0,a4 

move.l  StartList(a4) ,copllc(a5)  /Address  of  Startlist 

clr.w  copjmpl(a5) 


;Set  parameter  for  OpenLibrary 
.•Graphics  Library  open 


move.w  #$8060,dmacon(a5) 
jsr    permit (a6) 

;Free  memory  for  Copperlist 


; reenable  DMA 

; Task-Switching  on 


move .1  CLadr , a 1 
moveq  #CLsize,dO 
jsr    FreeMem(a6) 


;Set  parameter  for  FreeMem 
;Free  memory 


;Free  memory  for  Bitplanes 

FreePlane : 
move.l  Planeadr.al 
move.l  #Planesize*6,dO 
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jsr    FreeMem(a6) 


Ende: 

clr.l   dO 

rts 

; Program 

end 

;Variables 

CLadr :     dc 

1  0 

Planeadr :  dc 

1  0 

/Constants 

GRname:  dc.b 

"graphics 

library", 0 

; Program  end 

end 

Program  2:  Dual  play  field  &  smooth  scrolling 

This  program  uses  several  effects  at  once.  First  it  creates  a  dual-playfield 
screen  with  one  low-resolution  bit-plane  per  playfield.  Then  it  enlarges 
the  screen  window  so  that  no  borders  can  be  seen.  Finally,  it  scrolls 
playfield  1  horizontally  and  playfield  2  vertically. 

The  usual  routines  for  memory  allocation  and  release,  etc.  are  used  at  the 
start  and  end,  as  in  the  previous  example. 

Both  playfields  are  filled  with  a  checkerboard  pattern  of  16x16  pixel 
blocks. 

The  main  loop  of  the  program,  which  performs  the  scrolling,  first  waits  for 
a  line  within  the  vertical  blanking  gap,  in  which  the  operating  system  has 
already  processed  any  interrupt  routines  and  the  Copper  has  set  the 
BPLxPT's.  Then  it  increments  the  vertical  scroll  counter,  calculates  the 
new  BPLxPT  for  playfield  2,  and  writes  it  to  the  Copper  list. 

The  horizontal  scroll  position  results  from  separating  the  lower  four  bits 
of  the  scroll  counter  from  the  rest.  The  lower  four  bits  are  written  into  the 
BPLCON1  register  as  the  scroll  value  for  playfield  1,  and  the  5th  bit  is 
used  to  calculate  the  new  BPLxPT,  which  is  copied  to  the  Copper  list. 
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Both  the  horizontal  and  vertical  scroll  counters  are  incremented  from  0  to 
31  and  then  reset  to  0.  This  is  sufficient  for  a  smooth  scrolling  effect, 
since  the  pattern  used  for  the  playfields  repeats  every  32  pixels. 

***  Dual-Playfield  &  Scroll  Demo  *** 

; CustomChip-Register 

INTENA   =  $9A  ; Interrupt-Enable-Register  (write) 

INTREQR  =  $le  ; Interrupt-Request-Register  (read) 

DMACON  =  $96  ; DMA-Control  register  (write) 

COLOR00  =  $180  /Color  palette  register  0 

VPOSR   =  $4  ;half  line  position  (read) 

; Copper  Register 

COP1LC  =  $80  ,-Address  of  1.  Copperlist 

COP2LC  =  $84  ,-Address  of  2.  Copperlist 

COPJMP1  =  $88  ;Jump  to  Copperlist  1 

COPJMP2  =  $8a  ;Jump  to  Copperlist  2 

;Bitplane  Register 

BPLCON0  =  $100  ;Bitplane  control  register  0 

BPLCON1  =  $102  ;1  (Scroll  value) 

BPLCON2  =  $104  ;2  (SpriteoPlayf ield  Priority) 

BPL1PTH  =  $0E0  ; Pointer  to  1.  Bitplane 

BPL1PTL  =  $0E2  ; 

BPL1MOD  =  $108  ;Modulo-Value  for  odd  Bit-Planes 

BPL2MOD  =  $10A  ;Module-value  for  even  Bit-Planes 

DIWSTRT  =  $08E  ; Start  of  screen  windows 

DIWSTOP  =  $090  ;End  of  screen  windows 

DDFSTRT  =  $092  ; Bit-Plane  DMA  Start 

DDFSTOP  =  $094  ; Bit-Plane  DMA  Stop 

;CIA-A  Port  register  A  (Mouse  key) 

CIAAPRA  =  $bfe001 

;Exec  Library  Base  Offsets 

OpenLibrary  =  -30-522  ;LibName,Version/al,dO 

Forbid      =  -30-102 

Permit      =  -30-108 

AllocMem    =  -30-168  ;ByteSize,Requirements/dO,dl 

FreeMem     =  -30-180  ;MemoryBlock, ByteSize/al.dO 
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;  graphics  base 

StartList   =  38 

,-Misc  Labels 

Execbase  =  4 

Planesize  =  52*345 

Planewidth  =  52 

CLsize  =  5*4 

Chip  =  2 

Clear  =  Chip+$10000 

;***  Pre-programm  *** 

Start : 

/Request  memory  for  Bitplanes 


;Size  of  the  Bitplane 

;The  Copper list  contains  5  commands 

/request  Chip-RAM 

; clear  previous  Chip-RAM 


move.l  Execbase, a6 
move.l  #Planesize*2,dO 
move.l  #clear,dl 
jsr    AllocMem(a6) 
move .1  dO , Planeadr 
beq    Ende 


;memory  size  of  the  Planes 
.•Request  memory 
; Error!  ->  End 
/Request  memory  for  the  Copperlist 


moveq  #Clsize,dO 
moveq  #chip,dl 
jsr    AllocMem(a6) 
move .1  dO , CLadr 
beq    FreePlane 

; Build  Copperlist 

moveq  #l,d4 
move .1  dO , aO 
move . 1  Planeadr , dl 
move . w  #bpl lpth , d3 

MakeCL:  move.w  d3, (aO) + 
addq.w  #2,d3 
swap   dl 
move.w  dl, (a0)+ 
move.w  d3, (a0)+ 
addq.w  #2,d3 
swap   dl 


; Error!  ->  Free  memory  for  the  Planes 


;two  Bitplanes 
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move.w  dl, (a0)  + 
add.l   #planesize,dl 


; Address  of  the  next  Plane 


dbf 


d4,MakeCL 


move.l  #$fffffffe, (aO) 

;***  Main  prograram  *** 

;DMA  and  Task  switching  off 

jsr  forbid (a6) 
lea  $dff000,a5 
move.w  #$01e0,dmacon(a5) 


;End  of  the  Copperlist 


;Copper  initialization 

move . 1  CLadr , copl lc ( a5 ) 
clr.w  copjmpl(a5) 

;Playfield  initialization 

move.w  #0,color00 (a5) 

move.w  #$0f00,color00+2(a5) 

move.w  #$000f ,color00+18(a5) 

move.w  #$la64,diwstrt (a5) 

move.w  #$39dl,diwstop(a5) 

move.w  #$0020,ddfstrt(a5) 

move.w  #$00d8,ddfstop(a5) 

move.w  #%0010011000000000,bplcon0(a5)  ;Dual-Playfield  and 

clr.w  bplconl(a5)  ; Scroll  to  start  on  0 

clr.w  bplcon2(a5)  ;Playfield  1  or  Playfield  2 

move.w  #4,bpllmod(a5)       ;Modulo  on  2  Words 

move.w  #4,bpl2mod(a5) 


26,100 

313,465 

read  one  extra  word 


,-DMA  on 
move.w  #$8180,dmacon(a5) 

;Bitplanes  filled  with  checker  pattern 


move.l  planeadr.aO 
move.w  #planesize/2-l,d0 
move.w  #13*16, dl 
move.l  #$ffff0000,d2 
move.w  dl,d3 

fill:   move.l  d2,(a0)+ 
subq.w  #l,d3 


; loop  value 
;Height  =  16  Lines 
; checker  pattern 
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bne.s  continue 
swap   d2 
move.w  dl,d3 
continue:  dbf  dO,fill 


; pattern  change 


;Playfields  scroll 

clr.l  dO 

clr.l  dl 

move . 1  CLadr , al 

move . 1  Planeadr , aO 


.•vertical  Scroll  position 
/horizontal  Scroll  position 
/Address  of  the  Copperlist 
/Address  of  the  first  Bitplane 


/Wait  on  Raster  line  16   (for  the   Exec-Interrupts) 


wait :   move . 1  vposr ( a5 ) , d2 
and.l  #$0001FF00,d2 
cmp.l  #$00001000,d2 
bne.s  wait 


/read  Position 
/horizontal  Bits  masked 
/wait  on  line  16 


/Playfield  1  vertical  scroll 


addq . b 

#2,d0 

cmp.w 

#$80, dO 

bne.S 

novover 

clr.l 

dO 

novover 

move . 1 

d0,d2 

lsr.w 

#2,d2 

mulu 

#52, d2 

add.l 

a0,d2 

add.l 

#Planesize,d2 

move.w 

d2,14(al) 

swap 

d2 

move.w 

d2,10(al) 

/raise  vertical  Scroll  value 
/already   128  (4*32)? 

/Then  back  to  0 

/copy  scroll  value 

/copy  divided  by  4  s 

/Number  Bytes  per  line  *  Scroll  position 

/plus  Address  of  first  Plane 

/plus  Plane  size 

/give  End  address  for  Copperlist 


/Playfield  2  horizontal  scroll 


addq . b 

#l,dl 

cmp.w 

#$80, dl 

bne.S 

nohover 

clr.l 

dl 

nohover 

move . 1 

dl,d2 

lsr.w 

#2,d2 

move . 1 

d2,d3 

and.w 

#$FFF0,d2 

sub.w 

d2,d3 

/raise  horizontal  Scroll  value 
/already  128  (4*32) 

/then  back  to  0 

/copy  scroll  value 
/copy  divided  by  4 
/copy  Scroll  position 
/lower  4  Bit  masked 
/lower  4  Bit  in  d3  isolated 
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move.w  d4,bplconl(a5)  ;last  Value  in  BPLCON1 

move.w  d3,d4  ;new  scroll  value  to  d4 

lsr.w   #3,d2  /new  Address  for  Copperlist 

add.l  a0,d2  /calculate 

move.w  d2,6(al)  ;and  write  in  Copperlist 

swap   d2 

move.w  d2,2 (al) 

btst   #6,ciaapra  ;Mouse  key  pressed? 

bne.s  wait  ;N0  ->  continue 

; *  *  *  Check  programm  *  *  * 

/Activate  old  Copperlist 

move.l  #GRname,al  ;Set  parameter  for  OpenLibrary 

clr.l   dO 

jsr    OpenLibrary (a6)      /Graphics  Library  open 

move .1  dO , a4 

move.l  StartList (a4) , copllc(a5) 

clr.w  copjmpl(a5) 

move.w  #$83e0,dmacon(a5) 

jsr    permit (a6)  /Task-Switching  permitted 

/Free  memory  used  by  Copperlist 

move.l  CLadr.al  /Set  parameter  for  FreeMem 

moveq   #CLsize,dO 

jsr    FreeMem (a6)  /Free  memory 

/Free  memory  used  by  Bitplanes 
FreePlane : 

move . 1  Planeadr , al 

move.l  #Planesize*2,dO 

jsr    FreeMem (a6) 

Ende: 
clr.l  dO 
rts  /Program  ends 

/Variables 

CLadr:  del    0 

Planeadr :   dc . 1   0 
test:  del    0 

/Constants 
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GRname:   dc.b  "graphics. library" , 0 

end 
.•Program  end 

11.7.6        Sprites 


Sprites  are  small  graphic  elements  that  can  be  used  completely 
independently  of  the  playfields.  Each  sprite  is  16  pixels  wide  and  can 
have  a  maximum  height  of  the  entire  screen  window.  It  can  be  displayed 
anywhere  on  the  screen. 

Normally  a  sprite  is  in  front  of  the  playfield(s)  and  its  pixels  hide  the 
graphic  behind  it.  The  mouse  pointer,  for  example,  is  implemented  as  a 
sprite.  Up  to  eight  sprites  are  possible  on  the  Amiga.  A  sprite  normally 
has  three  colors,  but  two  sprites  can  be  combined  into  one  to  give  a 
fifteen-color  sprite. 

Construction  of  the  sprites 

Color  selection 

The  color  selection  for  sprites  is  very  similar  to  that  of  a  dual-playfield 
screen.  A  sprite  has  a  width  of  16  pixels,  which  are  represented  by  two 
data  words.  The  words  act  like  "mini  bit-planes,"  since  the  color  of  a  pixel 
is  formed  by  combining  corresponding  bits  of  both  the  words. 

The  color  of  the  first  (leftmost)  pixel  of  the  sprite  is  selected  by  the  high- 
value  bits  (bit  15)  of  the  two  words.  The  two  low-value  bits  (bit  0) 
determine  the  color  of  the  last  pixel.  Each  pixel  is  represented  by  two 
bits,  which  means  it  can  have  one  of  four  different  colors.  The  color  table 
is  used  to  determine  the  actual  color  from  this  value. 

There  are  no  special  color  registers  for  the  sprites.  The  sprite  colors  are 
obtained  from  the  latter  half  of  the  table,  color  registers  16-31.  This  means 
that  sprite  and  playfield  colors  do  not  come  into  conflict  unless  playfields 
with  more  than  16  colors  are  created. 

The  following  table  shows  the  assignment  of  color  registers  and  sprites: 
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Sprite  no. 

Sprite  data 

Color  register 

0&1 

00 

transparent 

01 

COLOR17 

10 

COLOR18 

1  1 

COLOR  19 

2&3 

00 

transparent 

01 

COLOR21 

10 

COLOR22 

1 1 

COLOR23 

4&5 

00 

transparent 

01 

COLOR25 

10 

COLOR26 

1 1 

COLOR27 

6&7 

00 

transparent 

01 

COLOR29 

10 

COLOR30 

1  0 

COLOR31 

Each  two  successive  sprites  have  the  same  color  registers. 

As  in  dual-playfield  mode,  the  bit  combination  of  two  zeros  does  not 
represent  a  color,  but  causes  the  pixel  to  be  transparent.  The  color  of 
anything  behind  this  pixel  is  visible  in  its  place,  whether  this  is  another 
sprite,  a  playfield,  or  just  the  background. 

If  three  colors  are  not  enough,  two  sprites  can  be  combined  with  each 
other.  The  two-bit  combinations  of  the  sprites  then  make  up  a  four-bit 
number.  Sprites  can  only  be  combined  in  successive  even-odd  pairs  (i.e., 
no.  0  with  no.  1,  no.  2  with  no.  3,  etc.).  The  two  data  words  of  the  higher- 
numbered  sprite  contribute  the  two  high-order  bits  of  the  total  4-bit 
value.  This  value  then  serves  as  a  pointer  to  one  of  fifteen  color  registers, 
with  the  value  zero  meaning  transparent.  The  color  registers  are  the  same 
for  all  four  sprite  pairs:  COLOR16  to  COLOR31. 


Sprite  data 

Color  register 

Sprite  data 

Color  register 

0000 

transparent 

1000 

COLOR24 

0001 

COLOR  17 

1001 

COLOR25 

0010 

COLOR18 

1010 

COLOR26 

001  1 

COLOR19 

101  1 

COLOR27 

0100 

COLOR20 

1  100 

COLOR28 

0101 

COLOR21 

1101 

COLOR29 

01  10 

COLOR22 

1110 

COLOR30 

0111 

COLOR23 

1111 

COLOR31 
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The  sprite  DMA 

The  Amiga  sprites  can  be  programmed  very  easily.  Almost  all  the  work  is 
handled  by  the  sprite  DMA  channels.  The  only  thing  needed  to  display  a 
sprite  on  the  screen  is  a  special  sprite  data  list  in  memory.  It  contains 
almost  all  the  data  needed  for  the  sprite.  The  DMA  controller  only  needs 
to  be  told  the  address  of  this  list  in  order  for  the  sprite  to  appear. 

The  DMA  controller  has  a  DMA  channel  for  each  sprite.  This  can  read 
only  two  data  words  in  each  raster  line.  This  is  why  a  normal  sprite  is 
limited  to  a  16-pixel  width  and  four  colors.  Since  these  two  data  words 
can  be  read  in  every  line,  the  height  of  a  sprite  is  limited  only  by  that  of 
the  screen  window. 

Construction  of  a  sprite  data  list 

A  sprite  data  list  consists  of  individual  lines,  each  containing  two  data 
words.  For  each  raster  line,  one  of  these  list  lines  is  read  via  DMA.  It  can 
contain  either  two  control  words  to  initialize  the  sprite,  or  two  data 
words  with  the  pixel  data. 

The  control  words  determine  the  horizontal  column  and  the  first  and  last 
line  of  the  sprite. 

After  the  DMA  controller  has  read  these  words  and  placed  them  in  the 
appropriate  registers,  it  waits  until  the  electron  beam  reaches  the  starting 
line  of  the  sprite.  Then  two  words  are  read  for  each  raster  line  and  are 
output  by  Denise  at  the  appropriate  horizontal  position  on  the  screen 
until  the  last  line  of  the  sprite  has  been  processed.  The  next  two  words  in 
the  sprite  data  list  are  again  treated  as  control  words. 

If  both  words  are  zero,  the  DMA  channel  ends  its  activity.  However,  it's 
also  possible  to  specify  a  new  sprite  position.  The  DMA  controller  then 
waits  for  the  start  line,  and  the  process  is  repeated  until  two  control 
words  with  the  value  zero  are  found  as  the  end  marker  of  the  list. 
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Construction  of  a  sprite  data  list  (Start  =  starting  address  of  the  list  in 
chip  RAM): 


Address 

Contents 

Start+4 
Start+8 
Start+12 
Start+4*n 

Start+4*(n+1) 

1st  and  2nd  data  words  of  the  1st  line  of  the  sprite 
1st  and  2nd  data  words  of  the  2nd  line  of  the  sprite 
1st  and  2nd  data  words  of  the  3rd  line  of  the  sprite 
1  st  and  2nd  data  words  of  the  nth  line  of  the  sprite 
0,0     End  of  the  sprite  data  list 

Construction  of  the  first  control  word: 


Bit  no.:       15      14      13      12      11      10      9       8       7       6       5       4       3       2        1        0 
Function:    E7     E6     E5     E4     E3     E2     E1     E0     H8     H7     H6     H5     H4     H3     H2     H1 


Construction  of  the  second  control  word: 


Bit  no.:  15     14      13      12      11      10      9        8       7       6       5       4  3        2        10 

Function:  L7     L6      L5      L4      L3      L2      L1      L0     AT     0       0       SHSH1       0        E8     L8     HO 

HO  to  H8  Horizontal  position  of  the  sprite  (HSTART) 

E0  to  E8  First  line  of  the  sprite  (VSTART) 

L0  to  L8  Last  line  of  the  sprite+1  (VSTOP) 

SHSH 1  Extra  bit  for  the  horizontal  position 

AT  Attach  control  bit 


The  (starting)  horizontal  position  and  the  starting  and  ending  vertical 
positions  of  the  sprite  are  expressed  with  nine  bits  each.  These  bits  are 
divided  somewhat  unpractically  between  the  two  control  registers. 

The  resolution  in  the  horizontal  direction  is  one  low-resolution  pixel, 
while  in  the  vertical  direction  it  is  one  raster  line.  These  values  are 
independent  of  the  mode  of  the  playfield(s)  and  cannot  be  changed. 

The  sprites  are  limited  to  the  screen  window  (set  by  DIWSTRT  and 
DIWSTOP).  If  the  coordinates  set  by  the  control  words  are  outside  this 
area,  the  sprites  are  only  partially  visible,  if  at  all,  since  all  points  that  are 
not  within  the  screen  window  are  cut  off. 

The  horizontal  and  vertical  start  positions  refer  to  the  upper  left  corner  of 
the  sprite.  The  vertical  stop  position  defines  the  first  line  after  the  sprite 
(i.e.,  the  last  line  of  the  sprite  +  1).  The  number  of  lines  in  the  sprite  is 
VSTOP -VSTART. 
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The  following  example  list  displays  a  sprite  at  the  coordinates  180,160, 
approximately  in  the  center  of  the  screen.  It  has  a  height  of  eight  lines. 
The  last  line  (VSTOP)  is  168.  If  you  combine  both  data  words  within  a 
line,  you  get  numbers  between  0  and  3,  which  represent  one  of  the  three 
sprite  colors  or  the  transparent  pixels.  This  makes  the  sprite  easier  to 
visualize: 

0000002222000000 
0000220000220000 
0002200330022000 
0022003113002200 
0022003113002200 
0002200330022000 
0000220000220000 
0000002222000000 

In  the  data  list  the  two  words  must  be  given  separately: 


Start : 

dew 

$A05A 

$A800 

HSTART  =  $B4,  VSTART 

=  $A0, 

dew 

%0000 

0000 

0000 

0000,%0000 

0011  1100 

0000 

dc  .w 

%0000 

0000 

0000 

0000,%0000 

1100  0011 

0000 

dc  .w 

%0000 

0001 

1000 

0000,%0001 

1001  1001 

1000 

dew 

%0000 

0011 

1100 

0000,%0011 

0010  0100 

1100 

dew 

%0000 

0011 

1100 

0000,%0011 

0010  0100 

1100 

dew 

%0000 

0001 

1000 

0000,%0001 

1001  1001 

1000 

dew 

%0000 

0000 

0000 

0000,%0000 

1100  0011 

0000 

dew 

%0000 

0000 

0000 

0000,%0000 

0011  1100 

0000 

dew 

0,0 

End  of  the 

sprite  data  list 

$A8 


The  AT  bit  in  the  2nd  control  word  determines  whether  two  sprites  are 
combined.  It  effects  only  those  sprites  with  odd  numbers  (sprites  1,  3,  5, 
7).  For  example,  if  it  is  set  in  sprite  1,  its  data  bits  are  combined  with  those 
of  sprite  0  to  make  four-bit  pointers  to  the  color  table.  The  order  of  the 
bits  is  then  as  follows: 


Sprite  1  (odd  number),  second  data  word: 
Sprite  1 ,  first  data  word: 
Sprite  0  (even  number),  second  data  word: 
Sprite  0,  first  data  word: 


Bit  3  (MSB) 
Bit  2 
Bit  1 

Bit  0  (LSB) 


If  two  sprites  are  to  be  combined  in  this  manner,  their  positions  must  also 
match.  If  this  is  not  the  case,  the  old  three-color  representation  is 
automatically  re-enabled.  The  simplest  thing  to  do  is  to  write  the  same 
control  words  in  the  two  sprite  data  lists.  We'll  now  give  an  example  of  a 
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sprite  data  list  for  a  fifteen-color  sprite.  For  the  sake  of  simplicity  our 
sprite  consists  of  only  four  lines.  Again,  we  first  visualize  the  sprite  by 
superimposing  the  data  words.  The  digits  represent  the  colors  of  the 
corresponding  pixels.  In  order  to  display  all  fifteen  colors  and 
transparent,  the  hexadecimal  digits  "A"  to  "F"  are  used. 

0011111111111100 
1123456789ABCD11 
1 1EFEFEFEFEFEF1 1 
0011111111111100 

The  structure  of  the  data  words  can  be  seen  from  line  2: 


Colors  of  the  sprite: 
Sprite  1,  data  word  2: 
Sprite  1,  data  word  1: 
Sprite  0,  data  word  2: 
Sprite  0,  data  word  1 : 


1123456789ABCD11 

0000000011111100 

0000111100001100 

0011001100110000 

1101010101010111 


Horizontal  position  (HSTART)  is  180.  The  first  line  of  the  sprite 
(VSTART)  is  160,  and  the  last  line  (VSTOP)  is  164. 

The  data  list  for  the  entire  sprite  looks  as  follows: 


StartSpriteO: 

dew   $A05A,  SA400  ;HSTART=$B4,    VSTART=$A0, 

dew  %0011  1111  1111  1100,%0000  0000  0000  0000 
dew  %1101  0101  0101  0111,%0011  0011  0011  0000 
dew  %1101  0101  0101  0111,%0011  1111  1111  1100 
dew  %0011  1111  1111  1100,%0000  0000  0000  0000 
dew  0,0 


VSTOP=$A4,  AT=0 


StartSpritel : 

dew  $A05A, $A480  ;HSTART=$B4,    VSTART=$A0,    VSTOP=$A4, 

dew  %0000   0000    0000    0000,%0000   0000    0000    0000 

dew  %0000   1111   0000   1100,%0000   0000   1111   1100 

dew  %0011   1111   1111   1100,%0011   1111   1111   1100 

dew  %0000   0000   0000   0000,%0000   0000   0000   0000 

dew  0,0 


AT=1 


Multiple  sprites  through  one  DMA  channel 

After  a  sprite  has  been  displayed,  the  DMA  channel  is  free.  In  the 
previous  example,  the  last  sprite  data  was  read  in  line  163.  After  that  the 
sprite  DMA  channel  is  turned  off  with  the  two  zeros  at  the  end  of  the 
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data  list.  But  as  we  mentioned  before,  it  is  also  possible  to  continue  using 
the  DMA  channel.  To  do  this,  simply  put  two  new  control  words  in  place 
of  the  two  zeros  in  the  data  list.  The  only  condition  is  that  there  must  be 
at  least  one  line  free  between  the  first  line  of  the  new  sprite  and  the  last 
line  of  the  previous  one.  For  example,  if  the  previous  sprite  extends 
through  line  163,  then  the  next  cannot  start  before  line  165.  The  reason 
for  this  is  that  the  two  control  words  must  be  read  in  the  line  in  between 
(164).  The  sprite  DMA  then  proceeds  as  follows: 


Line       Data  through  the  DMA  channel 


162 
163 
164 
165 
166 


Second-last  line  of  the  1st  sprite  through  this  channel 

Last  line  of  the  1st  sprite 

Control  words  of  the  2nd  sprite 

First  line  of  the  2nd  sprite 

Second  line  of  the  2nd  sprite 


The  following  example  displays  the  three-color  sprite  from  our  first 
example  in  two  different  positions  on  the  screen: 


Start : 


dew 
dew 
dew 
dew 
dew 
dew 
dew 
dew 
dew 


$A05A, 
%0000 
%0000 
%0000 
%0000 
%0000 
%0000 
%0000 
%0000 


dew 
dew 
dew 
dew 
dew 
dew 
dew 
dew 
dew 
dew 


$B096, 

%0000 

%0000 

%0000 

%0000 

%0000 

%0000 

%0000 

%0000 

0,0 


; First  sprite  through  this  DMA  channel  at  line  160  ($A0) 

,-Horizontal  position:  180  ($B4) 
$A800  ;HSTART  =  $B4,  VSTART  =  $A0,  VSTOP  =  $A8 
0000  0000  0000,%0000  0011  1100  0000 

0000  0000  0000,%0000  1100  0011  0000 

0001  1000  0000,%0001  1001  1001  1000 
0011  1100  0000,%0011  0010  0100  1100 
0011  1100  0000,%0011  0010  0100  1100 
0001  1000  0000,%0001  1001  1001  1000 
0000  0000  0000,%0000  1100  0011  0000 
0000  0000  0000,%0000  0011  1100  0000 

;Now  comes  the  second  sprite  over  this  DMA  channel 
;at  line  176  ($B0),  horizontal  position  300  ($12C) 

$B800     ;HSTART  =  $12C,  VSTART  =  $B0,  VSTOP  =  $B8 

0000  0000  0000,%0000  0011  1100  0000 

0000  0000  0000,%0000  1100  0011  0000 

0001  1000  0000,%0001  1001  1001  1000 
0011  1100  0000,%0011  0010  0100  1100 
0011  1100  0000,%0011  0010  0100  1100 
0001  1000  0000,%0001  1001  1001  1000 
0000  0000  0000,%0000  1100  0011  0000 
0000  0000  0000,%0000  0011  1100  0000 

;End  of  the  sprite  data  list 
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Activating  the  sprites 

After  a  correct  data  list  has  been  constructed  in  the  chip  RAM  and  the 
desired  colors  have  been  written  into  the  color  table,  the  DMA  controller 
must  be  told  at  what  address  the  list  is  stored  before  the  sprite  DMA  can 
be  enabled.  Each  DMA  channel  has  a  register  pair  in  which  the  starting 
address  of  the  data  list  must  be  written: 

SPRxPT  register  (SPRite  x  PoinTer,  points  to  data  list  for  sprite  DMA 
channel  x): 


Name 


Function 


$120 

$122 

$124 

$126 

$128 

$12A 

$12C 

$12E 

$130 

$132 

$134 

$136 

$138 

$13A 

$13C 

$13E 


SPROPTH 
SPROPTL 
SPR1PTH 
SPR1PTL 
SPR2PTH 
SPR2PTL 
SPR3PTH 
SPR3PTL 
SPR4PTH 
SPR4PTL 
SPR5PTH 
SPR5PTL 
SPR6PTH 
SPR6PTL 
SPR7PTH 
SPR7PTL 


Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  0  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  1  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  2  Bits  0-1 5 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  3  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  4  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  5  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  6  Bits  0-15 

Pointer  to  the  sprite  data  list  Bits  1 6-20 

for  sprite  DMA  channel  7 Bits  0-15 


All  SPRxPT  registers  are  write-only 

The  DMA  controller  uses  these  registers  as  pointers  to  the  current 
address  in  the  sprite  data  lists.  At  the  start  of  each  picture  they  contain 
the  address  of  the  first  control  word.  With  each  data  word  read  they  are 
incremented  by  one  word  so  that  at  the  end  of  the  picture  they  point  to 
the  first  word  after  the  data  list.  For  the  same  sprites  to  be  displayed  in 
each  frame,  these  pointers  must  be  set  back  to  the  start  of  the  sprite  data 
list  before  each  frame.  As  with  the  bit-plane  pointers  BPLxPT,  this  is  most 
easily  done  by  the  Copper  in  the  vertical  blanking  gap.  The  pertinent 
section  of  the  Copper  list  might  look  like  this: 

StartSpritexH  =  starting  address  of  sprite  data  list  for  sprite  x,  bits  16-19 

StartSpritexL  =  bits  0-15 

Copper listStart 

MOVE  #StartSpriteOH, SPROPTH      ; Initialize  sprite  DMA 

MOVE  #StartSpriteOL, SPROPTL      ; channel  0 
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MOVE  #StartSpritelH,SPRlPTH  ; Initialize  sprite  DMA 

MOVE  #StartSpritelL,SPRlPTL  ; channel  1 

MOVE  #StartSprite2H,SPR2PTH  ; Initialize  sprite  DMA 

MOVE  #StartSprite2L,SPR2PTL  ,-channel  2 

;Same  for  channels  3  to  6 

MOVE  #StartSprite7H, SPR4PTH  ; Initialize  sprite  DMA 

MOVE  #StartSprite7L,  SPR4PTL  ,-channel  7 

; Other  Copper  tasks 

WAIT  $FFFE  ;End  of  Copper  list 

There  is  no  way  to  turn  the  sprite  DMA  channels  on  and  off  individually. 
The  SPREN  bit  (bit  5)  in  the  DMACON  register  turns  the  sprite  DMA  on 
for  all  eight  sprite  channels.  If  you  don't  want  to  use  all  of  them,  the 
unused  channels  must  process  empty  data  lists.  To  do  this,  their  SPRxPT's 
are  set  to  two  memory  words  with  contents  of  zeros.  The  two  zeros  at 
the  end  of  an  existing  data  list  can  be  used  for  this. 

All  eight  SPRxPTs  must  always  be  initialized  within  the  vertical  blanking 
gap.  Even  if  the  data  list  is  nothing  but  the  two  zeros,  the  DMA  channel's 
SPRxPT  points  to  the  first  word  after  them  at  the  end  of  a  frame. 

Naturally,  the  SPRxPT  can  also  be  initialized  by  the  processor  in  the 
vertical  blanking  interrupt. 

As  the  last  step,  the  sprite  DMA  must  be  enabled.  As  previously 
mentioned,  this  is  done  for  all  eight  sprite  DMA  channels  by  using  the 
SPREN  bit  in  the  DMACON  register.  The  following  MOVE  command 
accomplishes  this: 

MOVE.W  #$8220,$DFF096       ;Set  SPREN  and  DMAEN  in  DMACON  register 

Moving  sprites 

The  values  of  the  two  control  words  in  the  sprite  data  list  determine  the 
position  of  a  sprite.  To  move  a  sprite,  these  values  must  be  changed  step 
by  step. 

This  can  be  done  directly  by  the  processor  when  using  the  appropriate 
MOVE  commands.  The  control  words  must  be  modified  at  the  right  time. 
Otherwise,  the  following  problem  can  occur: 

The  processor  modifies  the  first  control  word.  Before  it  can  change  the 
second  control  word,  the  DMA  controller  reads  both  words.  Since  they 
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no  longer  belong  together,  what  appears  on  the  screen  may  not  make 
any  sense. 

The  easiest  way  to  avoid  this  is  to  change  the  control  words  only  during 
the  vertical  blanking  interrupt,  after  the  Copper  has  initialized  the 
SPRxPT). 

The  sprite/playfield  priority 

The  priority  of  a  playfield  or  sprite  determines  whether  it  appears  in  front 
of,  behind,  or  between  the  other  screen  elements.  The  sprite  with  the 
highest  priority  appears  in  front  of  all  other  elements.  Nothing  can  cover 
it.  The  priority  of  a  sprite  is  determined  by  its  number.  The  lower  the 
number,  the  higher  the  priority.  Also,  sprite  0  has  priority  over  all  other 
sprites. 

For  the  playfields,  a  control  bit  determines  whether  number  1  or  2 
appears  in  front.  But  what  is  the  priority  of  the  sprites  in  reference  to  the 
playfields? 

On  the  Amiga  it  is  possible  to  position  the  playfields  almost  anywhere 
between  the  sprites.  The  sprites  are  always  handled  in  pairs  when  it 
comes  to  setting  the  priority  of  playfield  vs.  sprites.  The  pair 
combinations  are  the  same  as  those  used  for  fifteen-color  sprites,  always 
an  even-numbered  sprite  with  its  odd  successor: 

sprites  0  &  1,  sprites  2  &  3,  sprites  4  &  5,  sprites  6  &  7 

The  four  sprite  pairs  can  be  viewed  as  a  stack  of  four  elements.  If  you 
look  at  the  stack  from  above,  the  underlying  elements  can  only  be  seen 
through  holes  in  the  overlying  ones.  The  holes  correspond  to  the 
transparent  points  in  the  bit-planes  or  sprites  and  the  parts  of  the  screen 
that  a  sprite  cannot  cover  because  of  its  size.  The  order  of  elements  in  the 
stack  cannot  be  changed. 

But  two  of  the  elements,  namely  the  playfields,  can  be  placed  anywhere 
between  the  four  sprite  pairs.  Five  positions  are  possible  for  each 
playfield: 
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Position 

Order  from  front  to  back 

0 

PLF 

SPR0&1 

SPR2&3 

SPR4&5 

SPR6&7 

1 

SPR0&1 

PLF 

SPR2&3 

SPR4&5 

SPR6&7 

2 

SPR0&1 

SPR2&3 

PLF 

SPR4&5 

SPR6&7 

3 

SPR0&1 

SPR2&3 

SPR4&5 

PLF 

SPR6&7 

4 

SPR0&1 

SPR2&3 

SPR4&5 

SPR6&7 

PLF 

The  BPLCON2  register  contains  the  priority  of  the  playfields  with 
respect  to  the  sprites: 


BLPCON2  $104  (write-only) 


Bit  no.:       15-7        6  5  4  3 2 i  0 

Function:    Gen.        PF2PRI   PF2P2     PF2P1      PF2P0     PF1P2     PF1P1      PF1P0 


H 


BPLCON2  =  $0003 


PF2PRI 

If  this  bit  is  set,  playfield  2  appears  in  front  of  playfield  1 . 

PF1P0  toPFlPl 

These  three  bits  form  a  3-bit  number  that  determines  the  position  of 
playfield  1  (all  odd  bit-planes)  between  the  four  sprite  pairs.  Values  from 
0  to  4  are  allowed  (see  previous  table). 

PF2P0  to  PF2P2 

These  three  bits  have  the  same  function  as  bits  PF1P0  to  PF1P2,  but  for 
playfield  2  (all  even  bit-planes). 

Example: 


This  means  that  playfield  1  appears  before  playfield  2,  PF2P0-2  =  0, 
PF1P0-2  =  3.  This  yields  the  following  order,  from  front  to  back: 


PLF2  SPR0&1  SPR2&3  SPR4&5  PLF1  SPR6&7 


If  we  look  closely,  we  see  a  paradox.  The  PF2PRI  bit  is  0,  so  playfield  1 
should  appear  in  front  of  playfield  2.  The  order  previously  shown 
contradicts  this.  The  possible  consequences  of  such  a  situation  depend 
on  which  of  the  various  elements  are  present  at  a  given  pixel  location. 
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When  one  of  the  sprites  0  to  5  is  present  between  playfields  1  and  2,  its 
priority  causes  it  to  appear  in  front  of  playfield  1. 

Since  playfield  1  is  in  front  of  playfield  2,  the  sprite  is  visible  at  this  point, 
even  though  it  is  actually  behind  playfield  2.  In  contrast,  if  only  playfield 
2  and  the  sprite  are  at  a  given  position,  playfield  2  covers  the  sprite. 

This  is  because  the  playfield/playfield  priority  has  precedence  over  the 
sprite/playfield  priority. 

If  the  dual-playfield  mode  is  not  used,  there  is  only  one  playfield,  which  is 
formed  from  both  the  even  and  odd  bit-planes.  The  PF2PRI  and  PL2P0- 
PL2P2  bits  then  have  no  function. 

Collisions  between  graphic  elements 

It  is  often  very  useful  to  know  whether  two  sprites  have  collided  with 
each  other  or  with  the  background.  For  example,  in  a  game  program  this 
might  indicate  that  a  player  had  scored  a  hit. 

When  the  pixels  of  two  sprites  overlap  at  a  certain  screen  position  (i.e., 
both  have  a  non-transparent  pixel  at  the  same  coordinates),  this  is  treated 
as  a  collision  between  the  two  sprites.  A  collision  of  the  playfields  with 
each  other  or  with  a  sprite  is  also  possible. 

Each  recognized  collision  is  noted  in  the  collision  data  register, 
CLXDAT: 
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CLKDAT  $00E  (read-only) 


Bit  no.      Collision  between 


15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 


Unused 

Sprite  4  (or  5)  and  sprite  6  (or  7) 

Sprite  2  (or  3)  and  sprite  6  (or  7) 

Sprite  2  (or  3)  and  sprite  4  (or  5) 

Sprite  0  (or  1)  and  sprite  6  (or  7) 

Sprite  0  (or  1)  and  sprite  4  (or  5) 

Sprite  0  (or  1 )  and  sprite  2  (or  3) 

Playfield  2  (even  bit-planes)  and  sprite  6  (or  7) 

Playfield  2  (even  bit-planes)  and  sprite  4  (or  5) 

Playfield  2  (even  bit-planes)  and  sprite  2  (or  3) 

Playfield  2  (even  bit-planes)  and  sprite  0  (or  1 ) 

Playfield  1  (odd  bit-planes)  and  sprite  6  (or  7) 

Playfield  1  (odd  bit-planes)  and  sprite  4  (or  5) 

Playfield  1  (odd  bit-planes)  and  sprite  2  (or  3) 

Playfield  1  (odd  bit-planes)  and  sprite  0  (or  1) 

Playfield  1  and  playfield  2 


While  on  a  sprite,  any  non-transparent  pixel  can  cause  a  collision;  we  can 
specify  which  colors  of  the  playfields  are  to  be  considered  in  collision 
detection.  Moreover,  it  is  possible  to  include  or  exclude  any  odd- 
numbered  sprite  from  collision  detection.  All  this  can  be  set  with  the  bits 
in  the  collision  control  register,  CLXCON. 

CLXCON  $098  (write-only) 


Bit  no. 

Name 

Function 

15 

ENSP7 

Enable  collision  detection  for  sprite  7 

14 

ENSP5 

Enable  collision  detection  for  sprite  5 

13 

ENSP3 

Enable  collision  detection  for  sprite  3 

12 

ENSP1 

Enable  collision  detection  for  sprite  1 

11 

ENBP6 

Compare  bit-plane  6  with  MVBP6 

10 

ENBP5 

Compare  bit-plane  5  with  MVBP5 

9 

ENBP4 

Compare  bit-plane  4  with  MVBP4 

8 

ENBP3 

Compare  bit-plane  3  with  MVBP3 

7 

ENBP2 

Compare  bit-plane  2  with  MVBP2 

6 

ENBP1 

Compare  bit-plane  1  with  MVBP1 

5 

MVBP6 

Value  for  collision  with  bit-plane  6 

4 

MVBP5 

Value  for  collision  with  bit-plane  5 

3 

MVBP4 

Value  for  collision  with  bit-plane  4 

2 

MVBP3 

Value  for  collision  with  bit-plane  3 

1 

MVBP2 

Value  for  collision  with  bit-plane  2 

0 

MVBP1 

Value  for  collision  with  bit-plane  1 

The  ENSPx  bits  (ENable  SPrite  x)  determine  whether  the  corresponding 
odd-numbered  sprite  is  regarded  in  collision  detection.  For  example,  if  the 
ENSP1  bit  is  set,  a  collision  between  sprite  1  and  another  sprite  or  a 
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playfield  is  registered.  Such  a  collision  sets  the  same  bit  in  the  collision 
data  register  as  for  sprite  0.  Therefore,  it  is  not  possible  to  tell  by  looking 
at  the  register  contents  whether  sprite  0  or  sprite  1  caused  the  collision. 
Furthermore,  collisions  between  sprites  0  and  1  are  not  detected.  These 
facts  should  be  kept  in  mind  when  selecting  and  using  sprites. 

If  two  sprites  have  been  combined  into  one  fifteen-color  sprite,  the 
appropriate  ENSPx  bit  must  be  set  in  order  to  have  correct  collision 
detection. 

For  the  playfields,  the  programmer  can  set  which  combinations  of  the  bit- 
planes  generate  a  collision  and  which  do  not.  The  ENBPx  bits  (ENable 
Bitplane  x)  determine  which  bit-planes  are  considered  in  collision 
detection.  If  all  ENBPx  bits  of  a  playfield  are  set,  a  collision  is  possible  at 
every  pixel  whose  bit  combination  matches  that  of  the  MVBPx  bits 
(Match  Value  Bitplane  x). 

The  ENBPx  bits  determine  whether  the  bits  from  plane  x  are  compared 
with  the  value  of  MVBPx.  If  the  bits  of  all  planes  for  which  ENBPx  is  set 
match  the  corresponding  MVBPx  bits  for  a  given  pixel,  then  this  pixel 
can  generate  a  collision. 

Complicated?  An  example  makes  it  clearer: 

The  ENBPx  bits  are  set,  as  are  all  of  the  MVBPx  bits.  Now  only  those 
playfield  pixels  whose  bit  combinations  are  binary  111111  can  generate  a 
collision.  If  only  the  lower  three  MVBPx  bits  are  set,  then  a  collision  is 
possible  only  if  the  pixel  in  the  playfield  has  the  combination  000111. 

If  a  collision  is  to  be  allowed  for  all  pixels  with  the  bit  combinations 
0001 11, 0001 10, 000100  or  000101,  the  MVBP  bits  must  be  000100.  The 
lower  two  bits  should  always  satisfy  the  collision  condition,  so  the 
corresponding  ENBPx  bits  are  cleared.  The  ENBP  value  is  1 1 1 100. 

Examples  for  possible  bit  combinations: 
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ENBPx 

MVBPx 

Collision  possible  with  bit  pattern 

111111 

111111 

111111 

111111 

111000 

111000 

111100 

1111XX 

111100,111101,111110,111111 

011111 

X00000 

000000, 100000 

000000 

xxxxxx 

Collision  possible  with  any  bit  pattern 

The  values  of  bits  marked  with  an  x  are  irrelevant.  If  not  all  six  bit-planes 
are  active,  the  ENBPx  bits  of  the  unused  planes  must  be  set  to  0. 

The  various  combinations  of  the  ENBPx  and  MVBPx  bits  allow  a  variety 
of  different  collision  detection  strategies.  For  example,  the  CLXCON 
register  can  be  set  so  that  sprites  can  collide  only  with  the  red  and  green 
pixels  of  the  playfield,  but  not  with  other  colors.  Or  a  collision  may  be 
possible  only  at  the  transparent  pixels  of  playfield  1  if  the  underlying 
pixels  of  playfield  2  are  black,  etc. 

Other  sprite  registers 

Besides  the  SPRxPT  registers,  each  sprite  has  four  additional  registers. 
They  are  normally  supplied  with  data  automatically  by  the  DMA 
controller.  However,  it  is  also  possible  to  access  them  through  the 
processor. 


SPRxPOS 
SPRxCTL 
SPRxDATA 
SPRxDATB 


First  control  word 

Second  control  word 

First  data  word  of  a  line  (low  word) 

Second  data  word  of  a  line  (high  word) 


Again,  x  stands  for  a  sprite  number  from  0  to  7.  The  addresses  of  these 
registers  can  be  found  in  the  register  overview. 

The  DMA  controller  writes  the  two  control  words  of  a  sprite  direcdy  into 
the  two  registers  SPRxPOS  and  SPRxCTL.  When  a  value  is  written  into 
the  SPRxCTL  register,  whether  by  DMA  or  the  68030,  Denise  turns  the 
sprite  output  off.  The  sprite  will  no  longer  be  output  to  the  screen. 

The  DMA  controller  now  waits  for  the  line  specified  in  VSTART.  Then  it 
writes  the  first  two  data  words  into  the  SPRxDATA  and  SPRxDATB 
registers. 

Now  the  sprite  will  be  displayed,  because  writing  to  the  SPRxDATA 
register  causes  Denise  to  enable  the  sprite  output  again.  The  desired 
horizontal  position  from  the  SPRxCTL  and  SPRxPOS  registers  is 
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compared  with  the  actual  screen  column,  and  the  sprite  is  displayed  at 
the  correct  location  on  the  monitor. 

The  DMA  controller  writes  two  new  data  words  in  SPRxDATA/B  in  each 
line  until  the  last  line  of  the  sprite  (VSTOP)  is  past.  Then  it  fetches  the 
next  control  words  and  places  them  in  SPRxPOS  and  SPRxCTL.  This 
turns  the  sprite  off  again  until  the  next  VSTART  position  is  reached.  If 
both  control  words  were  zero,  the  DMA  controller  ends  the  sprite  DMA 
for  the  corresponding  channel  until  the  start  of  the  next  frame.  At  the 
end  of  the  vertical  blanking  gap,  it  starts  again  at  the  current  address  in 
SPRxPT. 

Displaying  sprites  without  DMA 

A  sprite  can  also  be  easily  displayed  without  the  DMA  channel.  You 
simply  write  the  desired  control  words  directly  into  the  SPRxPOS  and 
SPRxCTL  registers. 

Only  the  HSTART  position  and  the  AT  bit  have  to  contain  valid  values. 
VSTART  and  VSTOP  are  used  only  by  the  DMA  channel. 

You  can  begin  the  sprite  output  in  any  line  by  writing  the  two  data 
words  into  the  SPRxDATA  and  SPRxDATB  registers.  Since  writing  to 
SPRxDATA  enables  the  sprite  output,  it  is  better  to  write  to  SPRxDATB 
first.  If  the  contents  of  the  two  registers  are  not  changed,  they  are 
displayed  again  in  each  line.  The  result  is  a  vertical  column. 

To  turn  the  sprite  off  again,  simply  write  some  value  to  SPRxPOS. 

;***  Sprite  Demo  *** 

;Customchip  registers 

INTENA  =  $9A 

INTREQR  =  $le  ; Interrupt  request  register  (read) 

DMACON  =  $96  ;DMA  control  register  (write) 

COLOR00  =  $180, -Color  palette  register  0 

VPOSR   =  $4   ;Beam  position  (read) 

JOY0DAT  =  $A  /Mouse  position  for  port  0 

; Copper  registers 

COP1LC  =  $80   ,-Address  of  1st  Copperlist 
COP2LC  =  $84   ,-Address  of  2nd  Copperlist 
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COPJMPl  =  $88  ;Jump  to  Copperlist  1 
C0PJMP2  =  $8a  ;Jump  to  Copperlist  2 

;Bitplane  registers 

BPLCONO  =  $100  ;Bitplane  control  register  0 

BPLCON1  =  $102  ;1  (Scroll  values) 

BPLCON2  =  $104  ;2  (Spriteoplayf ield  priority) 

BPL1PTH  =  $OE0  ; Pointer  to  1st  bitplane 

BPL1PTL  =  $0E2  ; 

BPL1MOD  =  $108  ;Modulo  value  for  odd  bitplanes 

BPL2MOD  =  $10A  ;Module  value  for  even  bitplanes 

DIWSTRT  =  $08E  ; Start  of  screen  window 

DIWSTOP  =  $090  ;End  of  screen  window 

DDFSTRT  =  $092  ; Bitplane  DMA  start 

DDFSTOP  =  $094  ; Bitplane  DMA  stop 

; Sprite  registers 

SPR0PTH  =  $120  ; Pointer  to  sprite  data  list  for  sprite  1 
SPR0PTL  =  $122 
SPR1PTH  =  $124 
SPR1PTL  =  $126 


;CIA-A  port  register  A  (Mouse  button) 

CIAAPRA  =  $bfe001 

;Exec  Library  Base  Offsets 

OpenLibrary  =  -30-522  ;LibName,Version/al,dO 

Forbid  =  -30-102 

Permit  =  -30-108 

AllocMem  =  -30-168  ;ByteSize,Requirements/dO,dl 

FreeMem  =  -30-180   ;MemoryBlock, ByteSize/al, dO 

; graphics  base 

StartList  =  38 

; Other  labels 

Execbase  =  4 

Planesize  =  52*345  ;Size  of  bitplane 

Planewidth  =  52 

CLsize  =  19*4  ;Size  of  Copperlist  in  bytes 

Chip  =  2  ; Request  chip  RAM 
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Clear  =  Chip+$10000  ; Clear  previous  chip  RAM 

;***  start  program  *** 

Start : 

; Request  memory  for  bitplanes 

move.l  Execbase,a6 

move.l  #Planesize,dO   /Memory  requirement  of  planes 

move.l  #clear,dl 

jsr    AllocMem(a6)        ;Request  memory 

move . 1  dO , Planeadr 

beq        Ende  ; Error!  ->  End 


;Request  memory  for  Copperlist 

moveq  #Clsize,dO 
moveq   #chip, dl 
jsr    AllocMem(a6) 
move.l  dO,CLadr 

beq    FreePlane  ; Error!  ->  FreePlane 

.•Request  memory  for  sprite  data  list 

moveq  #Sprsize,dO 

moveq  #chip,dl 

jsr    AllocMem(a6) 

move .1  dO , Spradr 

beq    FreeCL 
;Set  up  Copperlist  in  chip  RAM 
; Bitplanepointer 

move . 1  CLadr , aO 

move.w  #bpllptl,d2 

move.l  Planeadr, dl 

bsr    setadr 

; Pointer  to  1st  sprite 

move.w  #spr0ptl,d2 

move . 1  Spradr , dl 

bsr    setadr 
; Remaining  (unused)  sprite  pointers 

moveq  #6,d0 

move.w  #sprlptl,d3 
spr_set : 

move.l  Spradr+Sprsize-4,dl 

move.w  d3,d2 

bsr  setadr 

addq.w  #4,d3 
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dbf     dO , spr_set 

move.l  #$fffffffe, (aO) 

;Copy  sprite  data  list 

move.w  #Sprsize/4-l,dO 
lea    Sprstart,aO 
move . 1  Spradr , al 
spr_copy : 

move.l  (aO)+,(al)+ 
dbf    dO , spr_copy 

.***  Main  program  *** 

/Disable  DMA  and  task-switching 

jsr  forbid (a6) 
lea  $dff000,a5 
move.w  #$0300,dmacon(a5) 

; Initialize  Copper 

move.l  CLadr, copllc (a5) 
clr.w  copjmpl(a5) 

/Initialize  playfield 


move.w  #0,color00 (a5)  ;Playfield  colors 

move.w  #$0f00,color00+2(a5) 

move.w  #$000f ,color00+34(a5)     /Sprite  colors 

move.w  #$00ff ,color00+36(a5) 

move.w  #$00f0,color00+38(a5) 

move.w  #$la64,diwstrt(a5)  ;26,100 

move.w  #$39dl,diwstop(a5)  ;313,465 

move.w  #$0028,ddfstrt(a5) 

move.w  #$00d8,ddfstop(a5) 

move.w  #%0001001000000000,bplcon0(a5) 

clr.w  bplconl(a5) 

move.w  #8,bplcon2 (a5) 

move.w  #2,bpllmod(a5) 

;DMA  on 

move.w  #$83a0,dmacon(a5)        ;Bitplane  &  sprite  DMA  on 

;Fill  bitplanes  with  checkerboard  pattern 

move . 1  planeadr , aO 
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move.w  #planesize/4-l,d0   ;Loop  counter 
move.w  #13*16,dl 

move.l   #$ffff0000,d2  checkerboard  pattern 

move.w  dl,d3 

fill:    move.l  d2,  (a0)+ 

subq.w  #l,d3 

bne.s  continue 

swap  62  ; Change  pattern 

move.w  dl,d3 
continue:  dbf  dO,fill  « 

;Wait  for  raster  line  16  (after  Exec -interrupts) 

wait:   btst   #6,ciaapra    ;Mouse  button  pressed? 
beq.s   endit 
move.l  vposr(a5),d2 
and.l   #$0001FF00,d2 
cmp.l   #$00001000, d2 
bne.S  wait 

;Move  sprite 

move.w  joy0dat(a5) ,d0  ;Mouse  position 

move.w  d0,dl 

and.w   #$ff,d0 

lsr.w  #8,dl 

add.w  #150, dO  ;Add  offset  for  null  position,   so 

add.w  #30, dl  ; sprite  always  remains  visible 

jsr    setcor  ,-Display  sprite  at  position  in  d0,dl 

bra.S  wait         ;No  ->  continue 

;***  End  program  *** 

,-Reactivate  old  Copperlist 

endit:   move.l  #GRname,al   ;Set  parameters  for  OpenLibrary 
clr.l  dO 

jsr    OpenLibrary (a6)  ;Open  Graphics  library 
move.l  d0,a4 

move.l  StartList(a4) ,copllc(a5) 
clr.w  copjmpl(a5) 
move.w  #$83a0,dmacon(a5) 
jsr    permit (a6) 

; Release  memory  for  sprite  data 
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move . 1  Spradr , a 1 
moveq   #Sprsize,dO 
jsr    FreeMem(a6) 

,-Release  memory  for  Copperlist 
FreeCL : 

move.l  CLadr.al    ;Set  parameters  for  FreeMem 

moveq   #CLsize,dO 

jsr    FreeMem (a6) 

/Release  memory  for  bitplanes 
FreePlane: 

move . 1  Planeadr , al 

move.l  #Planesize,dO 

jsr    FreeMem (a6) 

Ende: 


clr.l   dO 

rts  ;End  program 

; Subprograms 

;setadr  writes  the  Copper  commands  for  initializing  a  DMA  address  counter 

;in  the  Copperlist 

;a0  -  pointer  to  Copperlist  (incremented  by  setadr) 

;dl  -  to  written  address  (e.g.  bitplane) 

;d2  -  address  of  pointer  register,  low   (e.g.  bpllptl) 

setadr : 

move.w  d2,  (a0)+  ;move  ptl 

move.w  dl, (a0)+  ;addr  bits  1-15 

swap   dl 

subq.w  #2,d2     /switch  to  pth 

move.w  d2,(a0)+  ;move  pth 

move.w  dl,(aO)+  ;addr  bits  16-18 

rts 

;setcor  writes  the  X,Y  coordinates  of  the  sprite  to  the  sprite  data  list 

; in  the  chip  RAM 

;dO,dl  -  X,Y  coordinates 

/Address  of  sprite  data  list:  Spradr 

/Height  of  sprite  in  lines:  Sprhigh 

za0,d2,d3  are  used  internally 

setcor : 

movem.l  d0-d3/a0, - (sp) 

move.w  d0,d3   /HO  bit  to  second  control  word 

and.w   #l,d3   /Clear  rest 
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lsr.w   #l,dO   ;H1-H8  to  position 
tnove.w  d0,d2   ;  in  first  controlword 
and.w   #$ff,d2   ,-Clear  E0-E7 


move.w  dl,dO 

add.l  #Sprhigh,d0  ;Last  line  of  sprite  to  dO 

asl.w  #8,dl 

bcc  noE8 

bset  #2,d3 

noE8:    or.w  dl,d2 

asl.w  #8,d0 

bcc  noL8 

bset  #l,d3 

noL8:    or.w  d0,d3 

move . 1  Spradr , aO 

move .  w  d2 ,  ( aO )  + 

move.w  d3, (aO) 


;Set  E8  in  second  word 
;E0-E7  to  first  word 

;Set  L8 

;L0-L7  to  second  word 

Transfer  new  value  to  memory 


movem.l  (sp)+,d0-d3/a0 
rts 


(•Variables 


CLadr : 
Planeadr : 
Spradr : 
test: 


del 
del 
del 
del 


; Constants 


GRname :  de  b  " graphics . 1 ibrary " , 0 


; Sprite  data  list 

align  ;even 

Sprstart : 

dew  $a05a,$a800 
dew  %0000000000000000, 
dew  %0000000000000000, 
dew  %0000000110000000, 
dew  %0000001111000000, 
dew  %0000001111000000, 
dew  %0000000110000000, 
dew  %0000000000000000, 
dew  %0000000000000000, 

Sproff:  dew  0,0 

Sprend : 


%00000001111000000 
%00000110000110000 
%00001000110001000 
%00011001001001100 
%00011001001001100 
%00001000110001000 
%00000110000110000 
%00000001111000000 


Sprsize  =  Sprend-Sprstart 
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Sprhigh   =   9 

end 


11.7.7        ECS  Capabilities 


The  features  previously  described  (with  the  exception  of  the  2  Meg  chip 
RAM)  were  already  present  in  the  custom  chips  of  the  A1000.  But  in  the 
course  of  the  A3000's  development,  an  improved  chip  set,  called  the 
Enhanced  Chip  Set  (ECS),  was  also  developed.  To  ensure  software- 
compatibility,  the  developers  did  not  change  anything  in  the 
programming  of  previously  existing  modes.  However,  some  new  registers 
have  been  added  for  utilizing  the  additional  capabilities  of  the  new  chips: 

Super-HiRes  mode 

In  this  mode  the  horizontal  resolution  is  doubled  from  640  to  1280 
pixels/line. 

Freely  programmable  screen  display 

The  geometry  of  the  generated  video  image  can  be  freely  programmed  by 
selecting,  not  only  the  number  of  pixels  per  line,  but  also  the  number  of 
lines  and  the  video  frequency.  With  Super-HiRes  mode,  a  flicker-free 
picture  can  be  produced  even  at  a  resolution  of  640  x  512  pixels. 

Larger  bit-planes 

The  Blitter  now  supports  bit-planes  up  to  32768  x  32768  pixels  in  size. 

Expanded  genlock  capabilities 

Through  a  modified  "chromakey"  scheme,  every  video  register  can 
control  the  video  overlay. 

Super-HiRes  mode 

Previously  there  were  two  possibilities  for  horizontal  resolution:  HiRes 
(high  resolution)  and  LoRes  (low  resolution).  In  LoRes  mode  a  pixel  had 
a  duration  of  140  nanoseconds  (ns),  in  HiRes  mode  70  ns.  The  new 
Super-HiRes  mode  gives  double  the  resolution  of  HiRes  mode,  with  a 
duration  of  35  ns  per  pixel.  To  achieve  this,  Agnus  must  read  twice  as 
much  data  per  bit-plane  from  the  chip  RAM.  The  maximum  possible 
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number  of  bit-planes  has  been  halved  to  only  two,  representing  a 
maximum  of  four  colors  in  the  Super-HiRes  mode. 

Unfortunately,  the  entire  palette  of  4096  colors  is  not  accessible  in  the 
Super-HiRes  mode.  Only  64  colors  are  possible,  with  two  bit  each  for  the 
red,  green  and  blue  components.  The  programming  of  the  color  registers 
for  this  mode  follows  a  rather  complicated  scheme,  which  is  illustrated 
below. 


B 


Bit-plane  (color  0): 
Bit-plane  (color  1): 
Bit-plane  (color  2): 
Bit-plane  (color  3): 
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The  following  shows  the  color  selection  scheme  for  sprites,  which  are 
subject  to  the  same  limitations  as  the  playfields  in  Super-HiRes  mode. 
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Color  selection  for  Super-HiRes  sprites 


B 


Sprite  (color  16): 
Sprite  (color  17) : 
Sprite  (color  18): 
Sprite  (color  1 9) : 
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Although  the  Super-HiRes  mode  allows  fewer  colors  than  lower 
resolutions,  it  does  enable  a  more  precise  positioning  of  sprites.  An 
additional  bit  for  the  horizontal  position  in  the  second  control  word  of 
the  sprite  data  list  (bit  4)  allows  positioning  of  sprites  at  a  resolution  of 
70  nanoseconds  (i.e.,  two  Super-HiRes  pixels). 

The  Super-HiRes  mode  is  enabled  with  bit  6  of  the  first  bit-plane  control 
register,  BPLCON0.  The  bit  for  normal  HiRes  mode  (bit  15)  must  also  be 
cleared. 

Programmable  geometry  of  the  video  image 

Previously,  a  computer  conformed  to  either  the  PAL  or  the  NTSC  video 
standard,  and  the  geometry  of  the  computer's  video  image  (i.e.,  the 
number  of  lines  on  a  screen  and  the  number  of  pixels  in  a  line)  was  fixed 
accordingly.  With  the  Agnus  chip  of  the  A3000  the  geometry  of  the 
image  can  be  freely  programmed.  You  can  switch  between  the  two 
standards  or,  with  the  new  Super-HiRes  mode,  even  create  new  formats. 
For  example,  under  Kickstart  2.0,  there  is  a  productivity  mode  capable  of 
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producing  a  non-interlaced  display  of  640  x  480  pixels  (computed 
without  overscan). 

Some  new  registers  were  introduced  to  achieve  this  flexibility: 
HTOTAL     $1C0  (write-only)  Number  of  cycles  per  line 


Bit 
Function 


5      14      13      12      11      10      9       8       7        6       5       4 
h8     n7     h6     h5     h4     h3     h2     hi 


The  duration  of  each  line  is  the  number  of  clock  cycles  in  HTOTAL  +  1, 
the  clock  being  the  color  clock  CCK  (3.54  MHz,  with  a  280  ns  period). 
For  a  normal  Pal  image,  this  number  would  be  227.S,  for  the  productivity 
mode  114. 

The  number  of  lines  is  placed  in  the  VTOTAL  register. 

VTOTAL  $1C8  (write-only)  Highest  line  displayed 

There  are  a  total  of  VTOTAL  +  1  lines  displayed  per  image. 

The  previous  two  registers  are  used  to  establish  the  geometry  of  the 
video  image.  The  following  new  registers  determine  the  exact  timing  of 
the  creation  of  the  horizontal  and  vertical  synchronization  signals  and  of 
the  blanking  signals: 


$1E0 

$1CA 

$1DE 

$1C2 

$1E2 

$1C4 

$1C6 

$1CC 

$1CE 

VSSTART 

VSSTOP 

HSSTART 

HSSTOP 

HCENTER 

HBSTART 

HBSTOP 

VBSTART 

VBSTOP 

Starting  line  of  vertical  sync  signal 
Ending  line  of  vertical  sync  signal 
Starting  column  of  horizontal  sync  signal 
Ending  column  of  horizontal  sync  signal 
Starting  column  of  vertical  sync  in  interlace  mode 
Starting  column  of  horizontal  blanking  signal  (HBLANK) 
Ending  column  of  horizontal  blanking  signal  (HBLANK) 
Starting  line  of  vertical  blanking  signal  (VBLANK) 
Ending  line  of  vertical  blanking  signal  (VBLANK) 

In  connection  with  all  the  new  registers,  there  is  an  additional  register, 
BEAMCON0,  which  indicates  how  they  are  to  be  used: 
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BEAMCONO  $1DC  (write-only) 


Bit 

Name 

Function 

15 



14 

HARDDIS 

Disable  normal  blanking  signal 

13 

LPENDIS 

Disable  lightpen 

12 

VARVBEN 

Activate  VBSTART/STOP  registers 

11 

LOLDIS 

Disable  227/228  cycle/line  switching 

10 

CSCBEN 

Enable  composite-sync  bypass 

9 

VARVSYEN 

Enable  variable  V-sync 

8 

VARHSYEN 

Enable  variable  H-sync 

7 

VARBEAM 

Activate  HTOTAL/VTOTAL  registers 

6 

DUAL 

Special  Ultra-HiRes  mode  (not  implemented) 

5 

PAL 

Switch  Agnus  to  PAL 

4 

VARCSYNC 

Enable  variable  composite-sync 

3 

BLANKEN 

Output  blanking  signal  <!to/on?!>  composite-sync  pin 

2 

CSYTRUE 

Composite  sync  active-high 

1 

VSYTRUE 

Vertical  sync  active-high 

0 

HSYTRUE 

Horizontal  sync  active-high 

A  further  change  in  the  ECS  chip  set  affects  the  definition  of  the  screen 
window.  With  the  new  DIWHIGH  register,  the  window  can  now  be 
changed.  The  DIWHIGH  register  is  activated  by  setting  it  after  writing 
the  desired  values  to  the  old  DIWSTRT  and  DIWSTOP  registers: 

DIWHIGH  $1E4  (write  only) 


Bit 

Name 

Function 

15 

... 

14 

... 

13 

H8 

Horizontal  stop,  high-value  bit 

12 

... 

11 

... 

10 

V10 

9 

V9 

Vertical  stop,  three  high-value  bits 

8 

V8 

7 

— 

6 

... 

5 
4 

H8 

Horizontal  start,  high-value  bit 

3 
2 

V10 

19 

V9 

Vertical  start,  three  high-value  bits 

0 

V8 
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11.7.8  The  Blitter 


What  is  a  Blitter?  The  name  Blitter  stands  for  "block  image  transferor." 
This  is  the  main  task  of  the  Blitter:  moving  and  copying  data  blocks  in 
memory;  this  usually  involves  graphics  data.  The  Blitter  can  also  perform 
logical  operations  on  multiple  memory  areas  and  write  the  result  back 
into  memory.  It  accomplishes  these  tasks  very  quickly.  Simple  data 
moves  proceed  at  speeds  of  up  to  16  million  pixels  per  second. 

In  addition,  the  Blitter  can  fill  surfaces  and  draw  lines.  The  combination 
of  these  two  capabilities  enables  the  drawing  of  any  type  of  filled 
polygon. 

The  operating  system  uses  the  Blitter  for  almost  all  graphic  operations.  It 
handles  the  text  output,  draws  gadgets,  moves  windows,  etc.  In  addition, 
it  is  used  to  decode  data  from  the  diskette,  which  shows  that  the  many- 
faceted  capabilities  of  the  Blitter  are  not  limited  to  graphics. 

Using  the  Blitter  to  copy  data 

The  Blitter  always  follows  the  same  procedure  when  copying  data:  One 
to  three  memory  areas  and  the  data  sources  are  combined  together  using 
the  selected  logical  operation  and  the  result  is  written  back  into  memory. 
The  spectrum  ranges  from  simple  copying  to  complex  combinations  of 
multiple  data  areas.  The  addresses  of  the  source  data  areas,  named  A,  B 
and  C,  and  the  destination  area  D  can  be  anywhere  in  the  chip  RAM 
(fromOto$lFFFFF). 

The  Blitter  supports  "rectangular  memory  areas."  The  memory,  like  a 
bit-map,  is  divided  into  columns  and  rows.  It  is  also  possible  to  process 
small  areas  inside  a  large  bit-map  by  using  what  are  called  modulo  values. 
You  may  recall  that  such  modulo  values  are  also  used  in  playfields,  to 
define  bit-planes  that  are  wider  than  the  screen  window. 

The  following  steps  are  necessary  to  start  a  Blitter  operation: 

•  Select  the  Blitter  mode:  Copy  data. 

•  Select  the  source  data  areas  (not  all  three  sources  have  to  be  used) 
and  the  destination  area. 

•  Select  the  logical  operation. 
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Define  other  operating  parameters  (scrolling,  masking,  address 
direction). 

•       Define  the  window  in  which  the  Blitter  operation  is  to  take  place 
and  start  the  Blitter. 

Defining  the  Blitter  window 

You  may  wonder  why  we're  starting  with  a  discussion  of  the  last  step. 
Actually,  the  definition  of  the  desired  window  is  the  basis  of  all  the  other 
settings.  But  when  the  Blitter  is  programmed,  this  value  is  not  written  to 
the  appropriate  register  until  the  end,  because  that  is  what  starts  the 
Blitter.  For  that  reason,  this  point  also  appears  last  in  the  previous  list. 
However,  you  must  understand  the  Blitter  window  concept  in  order  to 
understand  the  other  values. 

The  Blitter  window  is  the  area  of  memory  that  is  to  be  processed  by  the 
Blitter  operation.  It  is  constructed  like  a  bit-plane  (i.e.,  divided  into  rows 
(lines)  and  columns)  where  a  column  corresponds  to  one  word  (two 
bytes).  The  number  of  words  in  the  window  is  equal  to  the  product  of 
the  rows  and  columns:  R*C. 

Since  the  desired  memory  area  is  divided  into  rows  and  columns,  the 
Blitter  is  very  well  suited  for  processing  bit-planes. 

However,  linear  memory  areas  can  also  be  accessed.  The  division  into 
rows  and  columns  simply  makes  the  programming  easier.  Actually,  the 
individual  lines  reside  at  contiguous  addresses  in  memory.  For  small  data 
fields  that  are  not  divided  into  rows  and  columns,  it  is  also  possible  to  set 
the  window  width  or  height  to  1. 

The  Blitter  processes  the  Blitter  window  line  by  line.  The  Blitter 
operation  begins  with  the  first  word  of  the  first  line  and  ends  with  the 
last  word  of  the  last  line.  The  BLTSIZE  register  contains  the  window 
size: 

BLTSIZE  $058  (write-only) 


Bit  no.:  15      14     13      12      11      10     9       8       7       6       5       4       3       2        i 6 — 

Function:       H9     H8     H7     H6     H5     H4     H3     H2     H1      HO     W5    W4    W3    W2    W1    WO 


H0-H9  These  ten  bits  represent  the  height  of  the  Blitter  window  in 

lines.  The  window  can  have  a  height  between  1  and  1024 
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lines  (210  =  1024).  A  height  of  1024  lines  is  selected  by 
setting  the  height  value  to  0.  For  all  other  values  the  height 
corresponds  directly  to  the  number  of  lines.  A  height  of  0 
lines  is  not  possible. 

WO  These  six  bits  represent  the  width  of  the  window.  The 

width  can  vary  between  1  and 

-W5  64  words  (2^  =  64).  In  terms  of  graphic  pixels,  this  can  be 

up  to  1024  pixels.  As  with  the  height,  the  maximum  width 
is  set  by  making  the  width  value  =  0. 

The  following  formula  is  applied  to  the  height  and  width  to  derive  the 
necessary  BLTSIZE  value:  BLTSIZE  =  Height*64  +  Width. 

It  must  be  modified  somewhat  when  using  the  two  extremes  (Height  = 
1024  and  Width  =  64): 


BLTSIZE  =  (Height  AND  $3FF) *64  +  (Width  AND  $3F) 


The  BLTSIZE  register  should  always  be  the  last  register  initialized.  The 
Blitter  is  automatically  started  when  a  value  is  written  to  BLTSIZE. 

The  Blitter  can  also  process  larger  windows  with  the  built-in  ECS  chips 
of  the  A3000.  For  this,  the  two  new  registers  BLITSIZV  and  BLITSIZH 
are  used: 


BLITSIZV 

BLITSIZH 

$5C 
$5E 

Number  of  lines  in  Blitter  window  (15  bits) 
Number  of  words  per  line  (1 1  bits),  start  Blitter 

Since  BLITSIZH  starts  the  Blitter,  BLITSIZV  must  be  written  first. 

Source  and  destination  data  areas 

During  a  Blitter  operation,  data  are  combined  together  from  completely 
different  areas  of  memory.  Even  though  the  Blitter  window  defines  the 
number  and  organization  of  data  words  to  be  processed,  the  positioning 
of  this  window  within  the  three  source  areas  and  the  destination  area 
must  still  be  specified. 

For  example,  suppose  that  you  want  the  Blitter  to  copy  a  small 
rectangular  graphic,  stored  somewhere  in  chip  RAM,  into  the  screen 
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memory.  For  this  simple  task  there  is  only  one  source  area.  The  selection 
of  the  Blitter  window  is  easy.  The  entire  graphic  is  to  be  copied,  so  the 
width  and  height  of  the  Blitter  window  correspond  to  that  of  the  graphic 
in  memory. 

So  that  the  Blitter  also  knows  where  this  graphic  can  be  found,  you  write 
the  address  of  the  first  word  of  the  top  line  into  the  appropriate  register. 

But  how  is  the  destination  area  defined?  The  graphic  is  to  be  copied  into 
the  screen  memory,  which  means  that  it  must  be  transferred  into  the 
current  bit-plane.  (For  the  sake  of  simplicity,  the  graphic  and  the  screen 
memory  are  each  assumed  to  consist  of  a  single  bit-plane.)  But  the  bit- 
plane  is  wider  than  the  small  graphic.  If  the  Blitter  were  to  copy  the 
graphic  directly  into  the  bit-plane,  the  result  would  not  appear  as  desired. 

In  addition  to  the  address  of  the  destination  area,  the  Blitter  must  also 
know  its  width.  This  information  is  communicated  by  a  modulo  value. 
The  modulo  value  is  added  to  the  address  pointer  after  each  line  of  the 
Blitter  window  is  processed.  The  words  that  are  not  affected  are  skipped 
and  the  pointer  indicates  the  start  of  the  next  line.  The  source  and 
destination  areas  have  independent  modulo  registers  so  that  they  can 
have  different  widths. 

The  following  figure  illustrates  our  example.  The  graphic  consists  of  five 
lines,  each  ten  words  wide.  The  numbers  represent  the  corresponding 
word  addresses  relative  to  the  initial  address  of  the  graphic.  The  bit-plane 
has  dimensions  of  ten  lines  by  twenty  words.  How  do  we  choose  the 
Blitter  window,  starting  addresses  and  modulo  values? 

The  Blitter  window  must  correspond  to  the  graphic,  since  the  latter  is  to 
be  copied  completely.  The  height  of  the  window  is  five  lines  and  the 
width  is  ten  words.  The  value  that  must  be  written  to  the  BLTSIZE 
register  is  330  (5*64  +  10)  or  hexadecimal  $014A. 

The  starting  address  of  the  source  data  is  equal  to  the  address  of  the  first 
word  of  the  graphic.  Since  the  line  width  of  the  graphic  is  equal  to  the 
line  width  of  the  Blitter  window,  the  modulo  value  for  the  source  is  0. 
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Graphic 
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Graphic    copied 
into   bit-plane 
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Plane  copy  principle 

The  modulo  value  must  now  be  calculated  for  the  destination  area.  To  do 
this,  simply  take  the  difference  between  the  actual  line  width  and  that  of 
the  Blitter  window. 

In  our  example,  this  is  20  words  minus  10  words:  The  modulo  value  for 
the  destination  area  is  10  words.  Modulo  values  must  be  specified  in 
bytes  in  the  Blitter  modulo  registers.  Modulo  value  =  modulo  in  words  * 

2. 

Finally,  the  Blitter  needs  the  starting  address  of  the  destination  data.  This 
determines  the  bit-plane  position  to  which  the  graphic  is  copied,  and  is 
equal  to  the  starting  address  of  the  bit-plane,  and  the  address  of  the  word 
at  which  the  upper  left  corner  of  the  graphic  is  to  be  placed.  In  our  figure 
this  is  the  address  of  the  bit-plane  and  24. 
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How  does  the  Blitter  operation  proceed? 

After  the  addresses  and  modulo  values  have  been  defined  and  the 
BLTSIZE  initialized,  the  Blitter  begins  copying  the  data.  It  fetches  the 
word  at  the  starting  address  of  the  source  data  and  stores  it  at  the 
destination  address.  Then  it  adds  one  word  to  both  addresses  and  copies 
the  next  word. 

This  is  repeated  Until  the  number  of  words  per  line  set  in  BLTSIZE  have 
been  processed.  Before  the  Blitter  continues  with  the  next  line,  it  adds 
the  modulo  values  to  the  address  pointers  so  that  the  next  line  starts  at 
the  right  address. 

After  all  lines  have  been  copied,  the  Blitter  turns  off  and  waits  for  its  next 
job.  After  a  Blitter  operation,  the  address  registers  contain  the  address  of 
the  last  word,  2,  and  the  modulo  value. 

The  address  registers  are  called  BLTxPT,  where  x  represents  one  of  the 
three  sources  A,  B,  C  or  the  destination  area  D.  Like  other  address 
registers,  they  occur  in  pairs,  with  one  for  bits  0-15  and  one  for  bits  16- 
20: 


Reg. 

Name 

Function 

048 

BLTCPTH 

Starting  address  of  Bits  16-20 

04A 

BLTCPTL 

source  data  area  C  Bits  0-15 

04C 

BLTBPTH 

Starting  address  of  Bits  16-20 

04E 

BLTBPTL 

source  data  area  B  Bits  0-15 

050 

BLTAPTH 

Starting  address  of  Bits  16-20 

052 

BLTAPTL 

source  data  area  A  Bits  0-15 

054 

BLTDPTH 

Starting  address  of  Bits  16-20 

056 

BLTDPTL 

destination  data  area  D  Bits  0-15 

Each  of  the  four  areas  has  its  own  modulo  register: 


060 
062 
064 
066 

BLTCMOD 
BLTBMOD 
BLTAMOD 
BLTDMOD 

Modulo  value  for  source  C 
Modulo  value  for  source  B 
Modulo  value  for  source  A 
Modulo  value  for  destination  D 

Copying  with  ascending  or  descending  addresses 

In  our  example  the  Blitter  worked  with  ascending  addresses  (i.e.,  it 
started  at  the  starting  address  and  incremented  until  reaching  the  ending 
address).  The  ending  address  is  logically  higher  than  the  starting  address. 
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However,  there  is  a  case  in  which  such  addressing  leads  to  errors:  the 
copying  of  a  memory  area  to  a  higher  address,  where  the  source  and 
destination  areas  partially  overlap.  Here  is  an  example: 


Result: 

Address 

Source  data 

Destination  data 

Desired 

Actual 

0 

Source  1 

2 

Source2 

4 

Source3 

6 

Source4 

Destl 

Sourcel 

Sourcel 

8 

Source5 

Dest2 

Source2 

Source2 

10 

Dest3 

Source3 

Source3 

12 

Dest4 

Source4 

ISourcel ! 

14 

Dest5 

Source5 

!Source2! 

The  five  source  data  words  are  to  be  written  to  the  address  of  the 
destination  data.  If  the  Blitter  begins  by  copying  Sourcel  to  the  desired 
destination  address  (Destl),  it  overwrites  Source4  before  the  data  there 
can  be  copied.  This  is  because  Source4  and  Destl  have  the  same  address 
(the  two  areas  overlap).  The  same  thing  happens  with  Source5  and 
Dest2. 

When  the  Blitter  reaches  the  address  of  Source4,  it  finds  Sourcel  instead. 
Sourcel  (not  Source4)  ends  up  in  Dest4,  and  Source2  (not  Source5)  ends 
up  in  Dest5.  Source4  and  Source5  are  lost. 

To  solve  this  problem,  the  Blitter  has  a  descending  address  mode  and  the 
ascending  mode. 

In  this  mode  it  starts  at  the  addresses  in  BLTxPT  and  decrements  these 
values  by  2  bytes  after  each  word  is  copied.  Also,  the  modulo  value  is 
subtracted  instead  of  added.  The  ending  address  lies  before  the  starting 
address. 

This  must  naturally  be  considered  when  initializing  the  BLTxPTs. 
Normally  these  are  set  to  the  upper  left  corner  of  the  Blitter  window  in 
the  given  data  area  (A,  B,  C  or  D).  In  descending  mode  the  addressing  is 
backwards.  Correspondingly,  BPLxPT  must  point  to  the  lower  right 
corner. 

The  modulo  and  BLTSIZE  values  are  identical  to  those  for  the  ascending 
mode. 
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In  general,  the  following  statements  can  be  made  regarding  mode 
selection: 


1. 


No  overlap  between  source  and  destination  areas: 

Either  ascending  or  descending  mode;  both  work  correctly  in  this 


case. 


2.  Source  and  destination  areas  overlap  partially,  and  the  destination  is 
before  the  source: 

Only  ascending  mode  works  correctly. 

3.  Source  and  destination  areas  overlap  partially,  and  the  destination  is 
after  the  source  (see  example): 

Only  descending  mode  works  correctly. 

Selecting  the  logical  operations 

As  previously  mentioned,  there  are  three  source  data  areas  associated 
with  the  destination  area.  The  logical  operations  are  always  performed  on 
a  bit  basis  so  that  the  destination  bit  D  must  be  obtained  from  the  data 
bits  A,  B  and  C. 

The  Blitter  recognizes  256  different  operations.  These  take  place  in  two 
steps: 

1.  Eight  different  boolean  equations  are  applied  to  the  three  source 
data  bits.  Each  of  these  yields  a  1  from  a  different  combination  of  A 
BandC. 

2.  The  eight  results  of  the  previous  equations  are  selectively  combined 
with  a  logical  OR.  The  result  is  the  destination  bit  D. 

The  term  "boolean  equation"  refers  to  a  mathematical  expression 
representing  a  combination  of  logical  operations.  This  type  of 
computation  is  called  boolean  algebra,  after  the  English  mathematician 
George  Boole  (1815  to  1864).  The  explanations  of  the  logical  functions 
of  the  Blitter  can  be  understood  without  a  knowledge  of  boolean 
algebra,  but  the  boolean  equations  are  nevertheless  included. 

There  are  eight  possible  combinations  of  three  bits.  Each  of  the  eight 
equations  is  true  for  one  of  them  (its  result  is  1).  By  using  the  eight 
control  bits  LFO  to  LF7  you  can  select  whether  the  result  of  the  equation 
has  any  effect  on  the  formation  of  D.  All  result  bits  whose  corresponding 
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LFx  bit  is  1  are  combined  with  a  logical  OR  function.  An  OR  function 
means  that  the  result  will  be  1  if  at  least  one  of  the  input  bits  is  1.  In  other 
words,  a  logical  OR  returns  a  0  only  if  all  inputs  are  0. 

With  the  eight  LFx  bits  you  can  choose  which  combinations  of  the  three 
input  bits  A,  B  and  C  will  cause  the  output  bit  D  to  be  1.  The  term  for  the 
eight  boolean  input  equations  is  "minterm."  The  following  table  gives  an 
overview  of  the  input  combinations  for  each  LFx  bit. 

In  the  Minterm  row,  a  lowercase  letter  represents  a  logical  inversion  of 
the  corresponding  input  bit.  Normally  this  is  indicated  with  a  bar  over  the 
letter. 

The  Input  bits  row  contains  the  bit  combination  for  which  the 
corresponding  equation  is  true.  The  order  of  the  bits  is  A  B  C. 


LF7 

LF6 

LF5 

LF4 

LF3 

LF2 

LF1 

LF0 

Minterm: 
Input  bits: 

ABC 
111 

ABc 
110 

AbC 
101 

Abe 
100 

aBC 
011 

aBc 
010 

abC 
001 

abc 
000 

Selecting  the  individual  minterms  is  easy.  For  each  input  combination  for 
which  the  output  bit  D  should  be  1,  set  the  corresponding  LFx  bit. 

In  our  first  example  we  simply  copy  the  source  data  from  A  directly  to  D. 
The  B  and  C  sources  are  not  used.  Which  minterms  must  be  selected  for 
this? 

D  can  be  1  only  when  A  =  1.  Only  the  upper  four  terms  LF4  to  LF7  come 
into  play,  since  A  =  1  only  for  these  terms.  Since  B  does  not  play  a  role, 
we  choose  a  term  in  which  B  is  1  and  a  term  in  which  B  is  0,  but  which 
are  otherwise  identical. 

Now  B  has  no  effect  on  D  because  the  remainder  of  the  equation  is 
unchanged  for  both  values  of  B  and  its  result  depends  only  on  this 
remainder.  The  same  holds  true  for  C.  If  we  look  at  the  table  of  input 
combinations,  we  see  that  LF4  to  LF7  must  be  activated.  Then  the  result 
depends  only  on  A,  since  for  any  combination  of  B  and  C,  one  of  these 
four  equations  is  always  true  for  A  =  1,  and  D  is  1.  If  A  =  0,  all  four  are 
false  and  D  =  0. 

If  you're  familiar  with  boolean  algebra,  you  can  obtain  the  appropriate 
minterms  yourself.  The  required  expression  is  A  =  D.  Since  B  and  C  are 
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always  present  in  the  Blitter,  they  must  be  integrated  into  the  equation  as 
well: 


|A*(b+B)*(c+C)=D 


The  term  x+X  is  always  true  (equal  to  1)  and  is  used  when  the  result  D  is 
independent  of  the  value  of  X.  To  get  the  required  minterms  simply 
multiply  it  out: 


1.  A*(b+B)*(c+C)=D 

2.  (A*b+A*B)*(c+C)=D 

3.  A*b*c+A*B*c+A*b*C+A*B  *C=D 


or  without  the  AND  operators: 


Abc+ABc+AbC+ABC=D 


Now  we  only  need  to  set  the  LFx  bits  of  the  corresponding  minterms. 
Boolean  algebra  has  helped  us  to  arrive  at  our  goal.  Here  are  some 
examples  of  common  Blitter  operations  and  the  corresponding  LFx  bit 
settings: 

•       Invert  a  data  area:  a  =D. 

Required  LFx  combination:  00001  111. 
Boolean  algebra:      a  =  D 

a*(b+B)*(c+C)  =  D 

(ab+aB)*(c+Q  =  D 

abc+aBc+abC+aBC  =  D 

Copy  a  graphic  to  a  bit-plane  without  changing  the  bit-plane's 
contents.  This  corresponds  to  logically  ORing  the  graphic  A  and 
the  bit-plane  B:  A  +  B  =  D. 

Required  LFx  combination:  11111 100. 

Boolean  algebra:      A  +  B  =  D 

A(b+B)(c4€)+B(a+A)(c+Q  =  D 
(Ab+AB)(c+Q+(Ba+BA)(c+C)  =  D 
Abc+ABc+AbC+ABC+Bac+BAc+BaC+BAC  =  D 
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Abc+ABc+AbC+ABC+aBc+aBC  =  D 
Here  are  the  rules  for  determining  the  LFx  bits  needed: 

1.  Determine  which  of  the  eight  ABC  combinations  should  cause  D  to 
bel. 

2.  Set  the  LFx  bits  for  these  combinations. 

3.  If  all  three  sources  aren't  needed,  you  must  select  all  combinations  in 
which  the  unused  bits  occur  and  in  which  the  desired  bits  have  the 
proper  value. 

Shifting  the  input  values 

For  some  tasks  the  Blitter's  limitation  to  word  boundaries  can  cause 
trouble.  For  example,  you  may  want  to  shift  a  certain  area  within  a  bit- 
map by  a  few  bits  (i.e.,  by  only  a  portion  of  a  word).  Or  perhaps  you 
want  the  Blitter  to  write  a  graphic  at  specific  screen  coordinates  that 
don't  match  a  word  boundary. 

In  order  to  handle  this  problem,  the  Blitter  has  the  capability  to  shift  the 
data  words  from  sources  A  and  B  to  the  right  by  up  to  15  bits.  This 
allows  it  to  move  the  data  to  any  desired  bit  position.  All  bits  that  are 
pushed  out  to  the  right  by  the  shift  operation  move  into  the  free  bits  in 
the  next  word.  The  entire  line  is  shifted  bit  by  bit.  A  device  called  a  barrel 
shifter  is  used  inside  the  Blitter  to  shift  the  words. 

It  requires  no  additional  time  for  the  shift  operation,  regardless  of  how 
many  bits  are  moved.  Adding  a  shift  of  the  data  does  not  limit  the  Blitter's 
speed  in  any  way. 

Example  for  shifting  data  by  three  bits: 
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Before: 


Data  word  1 
00011111  10011100 


Data  word  2 
0001010101111111 


Data  word  3 
11100001  11100101 


After: 


Data  word  1 
xxx00011  11110011 


Data  word  2 
1000001010101111 


Data  word  3 
11111100  00111100 


The  three  xxx  bits  depend  on  the  previous  data  word,  from  which  they 
are  shifted  out. 

Masking 

It  is  possible  to  use  the  Blitter  to  copy  a  graphic  whose  borders  are  not 
on  word  boundaries  from  screen  memory.  Data  that  is  to  the  left  of  the 
graphic  but  within  the  first  data  word  should  not  be  copied  along  with 
the  graphic  itself.  To  make  this  possible,  the  Blitter  can  apply  a  mask  to 
the  first  and  last  data  words  of  a  line.  This  means  that  you  can  choose 
which  bits  of  these  words  should  be  copied.  Undesired  data  can  be 
erased  from  the  edges  of  the  line. 

Only  source  A  can  be  masked  in  this  manner.  Two  registers  contain  the 
masks  for  the  two  edges.  A  bit  is  copied  in  the  Blitter  operation  only  if  it 
is  set  in  the  mask  register.  All  others  are  cleared. 

$044  BLTAFWM  BLiTter  source  A  First  Word  Mask 

Mask  for  the  first  data  word  in  the  line. 

$046  BLTALWM  BLiTter  source  A  Last  Word  Mask 

Mask  for  the  last  data  word  in  the  line. 

Bits  0-15  contain  the  corresponding  mask  bits.  For  example,  "1" 
represents  a  set  bit, "."  for  a  cleared  bit: 
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Column  1 

11111111 

111111 1111 

11 11 

11 1 

11 1 

11 11 

111111 1111 

11111111 


Graphic  data  in  the  bit-plane: 


Column  2 
1111111111111111 

11 1111 

1111 Ill 

11111 11 

11111 11 

1111 Ill 

11 1111 

1111111111111111 


Column  3 

1 11 

1111 1111 

11111 1111111 

1111111111111111 
1111111111111111 

11111 1111111 

1111 1111 

1 11 


FirstWordMask : 
0000000011111111 


LastWordMask : 
1111110000000000 


Column  1 

11111111 

1111 

11 

1 

1 

11 

1111 

11111111 


Column  3 

1 

1111 

11111 

111111.. . 
111111.  .. 

11111 

1111 

1 


Result: 

Column  2 
1111111111111111 

11 1111 

1111 Ill 

11111 11 

11111 11 

1111 Ill 

11 1111 

1111111111111111 

By  masking  out  the  unwanted  picture  elements  at  the  edges,  you  get  the 
desired  graphic. 

Note:  When  the  width  of  the  Blitter  window  is  only  one  word 

(BLTSIZE  width  =  1)  both  masks  come  together.  They 
both  operate  on  the  same  input  word.  Only  the  input  bits 
whose  mask  bits  are  set  in  both  masks  are  allowed  through. 

The  Blitter  control  registers 

The  Blitter  has  two  control  registers,  BLTCON0  and  BLITCON1.  The 
following  Blitter  control  bits  are  found  in  these  two  registers: 
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BLTCONO  $040 


Bit  no.      Name        Function 


15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 


ASH3 

ASH2 

ASH1 

ASHO 

USEA 

USEB 

USEC 

USED 

LF7 

LF6 

LF5 

LF4 

LF3 

LF2 

LF1 

LFO 


ASHO-3  contain  the  shift  distance 
for  the  input  data  from  source  A 
ASHO-3  =  0  means  no  shift 

Enables  the  DMA  channel  for  source  A 
Enables  the  DMA  channel  for  source  B 
Enables  the  DMA  channel  for  source  C 
Enables  the  DMA  channel  for  destination  D 
Selects  minterm  ABC  (bit  comb,  of  ABC:  111) 
Selects  minterm  ABc  (bit  comb,  of  ABC:  110) 
Selects  minterm  AbC  (bit  comb,  of  ABC:  101) 
Selects  minterm  Abe  (bit  comb,  of  ABC:  100) 
Selects  minterm  aBC  (bit  comb,  of  ABC:  01 1 ) 
Selects  minterm  aBc  (bit  comb,  of  ABC:  010) 
Selects  minterm  abC  (bit  comb,  of  ABC:  001) 
Selects  minterm  abc  (bit  comb,  of  ABC:  000) 


BLTCON1  $042 


Bit  no. 

Name 

Function 

15 

BSH3 

BSH0-3  contain  the  shift  distance 

14 

BSH2 

for  the  input  data  from  source  B 

13 

BSH1 

BSH0-3  =  0  means  no  shift 

12 

BSH0 

1-5 

Unused 

4 

EFE 

Exclusive  Fill  Enable 

3 

IFE 

Inclusive  Fill  Enable 

2 

FCI 

Fill  Carry  In 

1 

DESC 

DESC  =  1  switches  to  descending  mode 

0 

LINE 

LINE  =  1  activates  the  line  mode 

The  LINE  bit  switches  the  Blitter  into  its  line-drawing  mode.  If  you  want 
to  copy  data  with  the  Blitter,  LINE  must  be  0. 

Ascending  or  descending  addresses  can  be  selected  with  the  DESC  bit.  If 
DESC  =  0,  the  Blitter  works  in  ascending  mode;  if  DESC  =  1,  it  works  in 
descending  mode. 

The  EFE  and  IFE  bits  activate  the  surface-filling  mode  of  the  Blitter. 
They  must  both  be  0  for  the  Blitter  to  operate  in  the  normal  mode.  The 
FCI  bit  is  used  only  in  the  fill  mode. 
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The  Blitter  DMA 

The  data  from  the  source  areas  A,  B  and  C  and  the  output  data  D  are  read 
from  or  written  to  memory  through  four  DMA  channels.  This  Blitter 
DMA  can  be  enabled  for  all  channels  with  the  BLTEN  bit  (bit  6)  of  the 
DMACON  register.  The  Blitter  has  four  data  registers  for  its  DMA 
transfers: 


Addr. 

Name 

Function 

000 

BLTDDAT 

Output  data  D 

070 

BLTCDAT 

Data  register  for  source  C 

072 

BLTBDAT 

Data  register  for  source  B 

074 

BLTADAT 

Data  register  for  source  A 

The  DMA  controller  reads  the  needed  input  values  from  memory  and 
writes  them  to  the  data  registers.  When  the  Blitter  has  processed  the 
input  data,  BLTDDAT  contains  the  result.  The  DMA  controller  then 
transfers  the  contents  of  BLTDDAT  to  the  chip  RAM. 

The  DMA  transfer  through  these  four  registers  can  be  enabled  and 
disabled  by  using  the  four  USEx  bits.  For  example,  USEA  =  0  disables 
the  DMA  channel  for  data  register  A.  The  Blitter  continues  to  access  the 
value  in  BLTADAT,  so  with  each  new  word  from  the  active  sources  the 
same  word  is  fetched  from  source  A.  For  this  reason  unused  sources  must 
have  USEx  set  to  0  and  must  be  prevented  from  affecting  the  result  by 
the  appropriate  selection  of  minterms.  However,  the  same  word  is  always 
read  when  the  DMA  channel  is  disabled.  For  example,  you  can  fill  the 
memory  with  a  repeating  pattern  that  has  been  written  directly  into 
BLTxDAT 

In  addition  to  BLTEN,  three  other  bits  in  the  DMACON  register  pertain 
to  the  Blitter: 

BitlOBLTPRI 

This  bit  was  already  explained  in  the  Fundamentals  section  (11.7.2).  If  it 
is  1,  the  Blitter  has  absolute  priority  over  the  processor. 

Bit  14  BBUSY  (read-only) 

BBUSY  signals  the  status  of  the  Blitter.  If  it  is  1,  it  is  currently  performing 
an  operation. 
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After  the  Blitter  window  is  set  in  BLTSIZE  the  Blitter  begins  its  DMA 
and  sets  BBUSY  until  the  last  word  of  the  Blitter  window  has  been 
processed  and  written  back  into  memory.  It  then  ends  its  DMA  and 
clears  BBUSY. 

At  the  same  time  BBUSY  is  cleared,  the  B litter-finished  bit  in  the 
interrupt  request  register  is  also  set. 

Bit  13  BZERO 

The  BZERO  bit  indicates  whether  all  the  result  bits  of  a  Blitter  operation 
were  0.  In  other  words,  BZERO  is  set  when  none  of  the  operations 
performed  on  any  of  the  data  words  resulted  in  a  1 .  One  use  of  this  bit  is 
to  perform  collision  detection. 

The  minterms  are  set  so  that  D  is  1  only  if  the  two  sources  are  also  1.  If 
the  graphics  in  both  sources  intersect  at  least  one  point,  the  result  is  1 
and  BZERO  is  cleared.  At  the  end  of  the  Blitter  operation  you  can 
determine  whether  or  not  a  collision  occurred.  USED  is  set  to  0  in  this 
application  so  that  the  output  data  aren't  written  to  memory. 

Using  the  Blitter  to  fill  surfaces 

What  does  it  mean  to  "fill  a  surface"?  The  Blitter  understands  a  surface  to 
be  a  two-dimensional  area  of  memory  to  be  filled  with  points.  Normally 
this  surface  belongs  to  a  graphic  or  a  bit-plane. 

In  order  to  fill  a  surface,  the  Blitter  must  recognize  its  boundaries.  You 
need  a  definition  of  a  boundary  line  that  the  Blitter  can  understand. 
Many  fill  functions  exist  in  most  drawing  programs  and  also  in  Amiga- 
BASIC  with  the  PAINT  command. 

These  functions  cause  an  area  of  the  screen  to  be  filled,  starting  with 
some  initial  point,  until  the  program  encounters  a  boundary  line.  This 
allows  the  painting  of  completely  arbitrary  surfaces,  assuming  that  they 
are  enclosed  by  a  continuous  line.  The  Blitter  is  not  able  to  perform  such 
a  complex  fill  operation.  It  only  works  line  by  line  and  fills  the  free  space 
between  two  set  bits  which  mark  the  boundaries  of  the  desired  surface. 
The  following  examples  show  how  the  Blitter  fill  operation  works: 
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Correct  fill  operation: 


Before:  After: 

1.1 Ill 

1 1 111111111 

.  .  1 1 1111111111111 .  . 

.1 1...1 1 111111.  ..111111. 

.1 1...1 1 111111...  111111. 

.  .1 1 1111111111111.  . 

1 1 111111111 

.  .1 1 1111111111111.  . 


Incorrect  operation  due  to  improper  border  bits: 


Before:  After: 

.  .  .111 11111111111111. 


111..  -Ill 111111111 

.  .11.. .111.  .  .11 11111111111111. . .11. . 

.1 1...1 1 111111...  111111. 

.1 1...1 1 111111...  111111. 

. .11.  .  .111.  .  .11 11111111111111.  .  .11.  . 

1 1 111111111 

. .1111111111111 1111111111111111111. . 


In  the  first  example,  the  surface  is  bounded  properly  for  the  Blitter  and 
filled  correctly.  However,  in  example  2,  a  closed  boundary  line  is  drawn 
around  the  figure.  If  you  try  to  fill  such  a  graphic  with  the  Blitter,  chaos 
results. 

The  reason  for  this  is  the  algorithm  that  the  Blitter  uses.  It  is  extremely 
simple.  The  Blitter  starts  at  the  right  side  of  the  line.  As  it  proceeds  to  the 
left,  it  uses  the  Fill  Carry  bit  (FC)  to  determine  whether  an  output  bit  must 
be  set.  The  output  bit  corresponds  to  the  value  of  the  FC  bit,  which 
normally  (as  in  our  example)  starts  out  as  0. 

When  the  Blitter  encounters  an  input  bit  that  is  set,  the  value  of  the  FC 
bit  changes  (from  0  to  1  in  our  example).  This  causes  subsequent  output 
bits  to  have  the  new  value  (now  1),  until  another  set  bit  is  encountered  in 
the  input.  Then  the  FC  bit  will  be  switched  again  (back  to  0). 

In  this  way  the  area  between  two  set  bits  is  always  filled.  As  you  can  see 
from  the  second  example,  the  fill  logic  gets  confused  by  an  odd  number 
of  set  bits. 
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The  FCI  bit  (Fill  Carry  In)  in  BLTC0N1  determines  the  initial  value  of  the 
FC  bit.  If  FCI  is  cleared,  everything  proceeds  as  previously  described. 
But  if  FCI  =  1,  the  Blitter  starts  to  fill  from  the  edge  until  it  encounters  the 
first  set  input  bit.  The  fill  procedure  is  then  reversed. 


Example  of  the  effect  of  the  FCI  bit: 


Output  graphic 

1 1 

...1 1.. 

..1 1.1 1. 

-.1 1.1 1. 

...1 1.. 

1 1 


FCI=0 
...1111111... 
.11111111111. 
111111.111111 
111111.111111 
.11111111111. 
. . .1111111.  .. 


FCI=1 

1111111 111111 

11111 1111 

1111 111 111 

1111 111 111 

11111 1111 

1111111 111111 


In  the  examples  up  to  now,  the  input  bits  (the  boundaries  of  the  surface) 
have  been  retained  in  the  filled  graphic.  This  is  always  the  case  when  the 
fill  mode  is  activated  by  setting  the  ICE  bit  (Inclusive  fill  Enable)  in  the 
BLTCON1  register. 

In  contrast  to  this  is  the  ECE  mode  (Exclusive  fill  Enable),  which  is 
enabled  by  setting  the  bit  with  this  name  in  BLTCON1.  In  this  mode  the 
boundary  bits  at  the  left  edge  of  a  filled  surface  (whenever  the  fill  carry 
bit  changes  from  1  to  0)  are  not  retained  in  the  output  picture. 

This  causes  all  surfaces  to  be  one  pixel  narrower.  Only  in  the  ECE  mode 
is  it  possible  to  get  surfaces  with  a  width  of  only  one  bit.  It  is  impossible 
in  the  ICE  mode  because  the  definition  of  a  surface,  however  narrow, 
requires  at  least  two  boundary  bits,  both  of  which  will  appear  in  the 
output. 

Difference  between  ICE  and  ECE  modes: 


Output  graphic 

11 11 

1.  .  .1 1.1 

.. .1. ..11..1. .1. .1 

1 11..  .11..  .1 

..1 1 

1 1. 

1...1...11.. 


ICE 

11 11 

11111 111 

...111111111.. 1111 
111111111111111111 
..1111111111111111 

1111111111111. 

11111. ..11.. 


ECE 
1 1 

1111. ....11 

1111. 111. ..Ill 

.1111111.1111.1111 
...111111111111111 

111111111111. 

1111 1.. 


Bit  wise  operation  of  the  different  fill  operations: 
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Input  pattern:  11010010 


FCI  =  0 

FCI  =  1 

Bit  no. 

Input  bit 

FC         ICE           ECE 

FC         ICE            ECE 

- 

11010010 

FC=FCI 

FC=FCI 

0 

0 

0              0              0 

1              1              1 

1 

1 

1             10             10 

0             11             01 

2 

0 

1            110           110 

0           011           001 

3 

0 

1          1110         1110 

0         0011         0001 

4 

1 

0        11110       01110 

1        10011        10001 

5 

0 

0      011110      001110 

1       110011       110001 

6 

1 

1     1011110    1001110 

0    1110011    0110001 

7 

1 

0  11011110  01001110 

1  11110011  10110001 

FC=FCI  means  that  the  FC  bit  assume 

BLTCON1  at  the  start  of  the  fill  operation. 

How  is  a  Blitter  fill  operation  started?  The  Blitter  can  perform  this  fill 
operation  in  addition  to  an  ordinary  copy  procedure.  It  is  enabled  by 
setting  either  the  ICE  bit  or  the  ECE  bit  in  BLTCON1  depending  on  the 
desired  mode.  The  Blitter  forms  the  output  data  D  from  the  three  sources 
A,  B  and  C  and  the  selected  minterms  as  usual.  If  neither  of  the  two  fill 
modes  is  active,  the  Blitter  writes  this  data  directly  to  its  output  data 
register  (BLTDDAT,  $000).  From  there  the  data  is  written  to  memory  via 
DMA  if  USED  =  1. 

In  the  fill  mode,  the  output  data  D  is  used  as  input  data  for  the  fill  circuit. 
The  result  of  the  fill  operation  is  then  written  into  the  output  data  register 
BLTDDAT. 

The  following  steps  are  needed  to  perform  a  fill  operation: 

Select  the  BLTxPT,  BLTxMOD  and  minterms  so  that  the  output 
data  D  contains  the  correct  boundary  bits  for  the  surface  to  be 
filled. 

•  Select  descending  mode  (the  Blitter  fills  from  right  to  left  and  this 
works  only  when  the  words  are  referenced  with  descending 
addresses). 

•  Select  the  desired  fill  mode:  set  ICE  or  ECE;  set  or  clear  FCI  as 
desired. 

LINE  =  0  (Line  mode  off). 
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Set  BLTSIZE  to  the  size  of  the  graphic  to  be  filled. 

The  Blitter  now  begins  the  fill  procedure.  When  it  is  done,  it  sets 
BLTBUSY  to  0  as  usual.  The  speed  of  the  Blitter  is  not  limited  by 
activating  the  fill  mode. 

The  Blitter  can  fill  surfaces  at  a  maximum  speed  of  16  million  pixels  per 
second.  The  major  application  of  the  fill  mode  is  in  drawing  filled 
polygons.  The  desired  polygon  is  drawn  in  an  empty  memory  area  using 
line  mode  and  then  filled  very  rapidly  by  the  Blitter. 

Using  the  Blitter  to  draw  lines 

The  Blitter  is  an  extremely  versatile  tool.  In  addition  to  its  excellent 
capabilities  for  copying  data  and  filling  surfaces,  it  has  a  powerful  mode 
for  drawing  lines.  Like  the  other  Blitter  modes,  the  line  mode  is  extremely 
fast:  up  to  a  million  pixels  per  second. 

What  exactly  is  "drawing  lines"?  When  a  line  is  drawn,  two  points  are 
connected  to  each  other  by  a  continuous  series  of  points.  Since  the 
resolution  of  a  computer  graphic  is  limited,  the  optimal  points  cannot 
always  be  chosen.  The  actual  pixels  may  lie  slightly  above  or  below  the 
intended  ideal  line.  Such  a  line  usually  resembles  a  staircase.  The  higher 
the  resolution,  the  smaller  the  steps,  but  they  can  never  be  completely 
eliminated. 

Example  of  a  line  in  a  computer  graphic: 

The  two  points  are  connected  by  a  line 


1.  .  .  111. 

Ill 

1111 

Ill 

.1 Ill 


The  Blitter  can  draw  lines  up  to  a  length  of  1024  pixels.  Unfortunately, 
you  cannot  specify  the  coordinates  of  the  two  endpoints.  Like  solid 
surfaces,  lines  must  be  defined  in  a  style  recognizable  to  the  Blitter. 
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First,  the  Blitter  needs  to  know  the  octants  in  which  the  line  is  located. 
The  coordinate  system  is  divided  into  eight  parts;  you'll  find  that  the 
octants  are  found  in  many  graphic  processors. 


\0 

0  / 

E 

\ 

SUDsO 
SULsl 
AULsl 

"  ii  ii 
Q  _l  _l 
3  3  3 

«  to  < 

/ 

0 

SUD=1 
SULsl 
AUL=1 

©X 

y® 

SUDsl 
SULsl 
AULsO 

SUD=1 
SUL=0 
AUL=1 

©y 

\© 

(X  axis) 

SUD=1 
SULsO 
AULsO 

4 

SUDsO 
SUL=1 
AULsO 

SUDsO 
SULsO 
AULsO 

\H 

'B 

(Y  axis) 

0\ 

D 
o- 


number  of  octants 


values  of  SUD/SUL/AUL  bits 


Blitter  octants 

The  figure  shows  this  division.  The  starting  point  of  the  line  is  located  at 
the  origin  of  the  coordinate  system  (the  intersection  of  the  X  and  Y 
axes).  The  end  point  is  located  in  one  of  the  eight  octants,  according  to 
its  coordinates.  The  number  of  this  octant  can  be  determined  with  three 
logical  comparisons.  XI  and  Yl  are  the  coordinates  of  the  start  point  and 
X2  and  Y2  are  those  of  the  end  point: 
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If  XI  is  less  than  X2,  the  end  point  is  in  octant  0, 1,  6  or  7,  while  if  XI  is 
greater  than  X2,  it  is  in  2, 3, 4  or  5.  If  XI  and  X2  are  equal,  it  is  on  the  Y 
axis.  Then  all  eight  octants  are  possible. 

Similarly:  If  Yl  is  less  than  Y2,  possible  octants  of  the  end  point  are  0, 1, 2 
and  3,  and  if  Yl  is  greater  than  Y2,  the  octants  are  4,  5,  6  and  7.  If  Yl  = 
Yl,  all  are  possible. 

For  the  last  comparison  we  need  the  X  and  Y  differences:  DeltaX  =  1X2- 
XII,  DeltaY  =  IY2-Y1I.  If  DeltaX  is  greater  than  DeltaY,  the  end  point  can 
be  located  in  octant  0,  3,  4  or  7.  If  DeltaX  is  less  than  DeltaY,  it  is  in 
octant  1 , 2, 5  or  6.  For  DeltaX  =  DeltaY,  all  octants. 


Ay 


Ending   point 
B(x  v  y  2) 


Starting  point 
A(x  v  y  2) 


Ax 


Selection  of  start  and  end  points 

The  end  point  is  located  in  the  octant  that  occurred  in  all  three 
comparisons.  If  a  point  is  on  the  border  between  two  octants,  it  doesn't 
matter  which  is  chosen. 
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The  digits  in  the  "Code"  column  correspond  to  the  circled  numbers  in  the 
figure.  The  Blitter  needs  a  combination  of  three  bits,  depending  on  the 
octant  in  which  the  end  point  of  the  line  is  located.  The  bits  are  called 
SUD  (Sometimes  Up  or  Down),  SUL  (Sometimes  Up  or  Left)  and  AUL 
(Always  Up  or  Left). 

"Code"  is  the  3-bit  number  formed  by  these  bits  (SUD  =  MSB  and  AUL 
=  LSB). 

When  programming  the  line  you  must  first  determine  the  octant  of  the 
end  point  and  then  write  the  corresponding  code  value  into  the  Blitter. 

Selecting  the  correct  octant: 


Point  coordinates      Octant     Code       Point  coordinates 


Y1  <=  Y2 
X1  <£  X2 
DeltaX  >=  DeltaY 

Y1<=Y2 
X1  <=  X2 
DeltaX  <=  DeltaY 

Y1  <=  Y2 
X1  >=  X2 

DeltaX  <=  DeltaY 

Y1  <=  Y2 
X1>=X2 

DeltaX  >=  DeltaY 


Octant 


Code 


Y1  >=  Y2 
X1  >=  X2 
DeltaX  >=  DeltaY 

Y1  >=  Y2 
X1>=X2 
DeltaX  <=  DeltaY 

Y1  >=  Y2 
X1  <=  X2 
DeltaX  <=  DeltaY 

Y1  >=  Y2 
X1  <=  X2 

DeltaX  >=  DeltaY 


Lines  with  patterns 

When  drawing  a  line,  the  Blitter  uses  a  mask  to  determine  whether  the 
points  of  the  line  should  be  set,  cleared,  or  given  a  pattern.  The  mask  is  16 
bits  wide,  so  the  pattern  repeats  every  16  points.  The  relationship 
between  the  pattern  and  the  appearance  of  the  line  can  best  be 
understood  with  a  couple  of  examples: 

=0,  "1"  =  1,  A  =  start  point  and  B  =  end  point) 

Output  picture:  Mask  =  "1111111111111111": 
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. .1111 

1111.  . 
.. .111 

B. 

111... 

11 

11. 

11 

11 

111... 

...111 

..A 

..11111111.. 

11111111 11B 

..  .111 11111. 

.11 11.11. 

11 Ill 11 

11 111 11 

.11111 11. 

.11111 111... 

All... .11111111 


Zero  bits  in  the  mask  cause  line  points  to  be  cleared: 
Output  picture:  Mask  =  "0000000000000000": 


.. 11111111111111111.. B 
..11111111111111111.. 
..11111111111111111.. 
. .11111111111111111.  . 
.  .11111111111111111. . 
. .11111111111111111.  . 
..11111111111111111.  . 
A. 11111111111111111.  . 


..11111111111111111. 

. .11111111111111 

..111111111111.. 111. 
. .111111111. . .11111. 
. .111111. . .11111111. 
. .1111.. 11111111111. 
..1.. .1111111111111. 
A.. 1111111111111111. 


If  we  combine  ones  and  zeros  in  the  mask,  the  line  takes  on  a  pattern: 
Mask  =  "1111111000111000 


.Allllll. 


.111. 


.111111. 


.111.. .11. 


.11111. 


.111. . .111. 


.1111. ..B 


Drawing  boundary  lines 

In  the  section  on  filling  surfaces  with  the  Blitter,  we  explained  that  the 
boundary  lines  of  these  surfaces  can  only  be  one  pixel  wide. 

If  these  lines  are  drawn  with  the  Blitter,  it's  possible  that  several  line 
points  lie  on  the  same  horizontal  line.  To  prevent  this,  the  Blitter  can  be 
made  to  draw  lines  with  only  one  point  per  raster  line: 
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Normal  line: 

1111 

1111 

.........1111..  .......  4, 

..:. lilt :..;.... .. .; 

1111 


Line  with  one  point/raster  line: 

1... 

1 

. :.;!.. ..........  -."; : r   :-  '  -'•■'-■ 

1 


The  definition  of  slope 

So  the  Blitter  knows  where  to  draw  the  line,  it  needs  a  Blitter-style 
definition  of  the  slope  of  the  line.  This  slope  is  formed  from  the  results  of 
three  terms,  all  based  on  the  DeltaX  and  DeltaY  values,  as  explained  in 
the  section  on  octants  (DeltaY  and  DeltaX  represent  the  width  and 
height  of  the  rectangle  for  which  the  line  forms  a  diagonal). 

First  the  two  values  must  be  compared  with  each  other  to  find  the 
larger/smaller  of  the  two.  The  smaller  delta  is  called  Sdelta  and  the  larger 
one  is  called  Ldelta.  Then  the  three  expressions  required  by  the  Blitter 
are  as  follows: 

1.  2*Sdelta 

2.  2*Sdelta  -  Ldelta 

3.  2*Sdelta  -  2*Ldelta 

Also,  the  Blitter  has  a  SIGN  flag  which  must  be  set  to  1  if  2*Sdelta  < 
Ldelta. 

Register  functions  in  line  mode 

The  Blitter  uses  the  same  registers  when  drawing  lines  as  it  does  when 
copying  data  (it  doesn't  have  any  more),  but  the  functions  change: 

BLTAPTL  The  value  of  the  expression  "2*Sdelta-Ldelta"  must  be 

written  into  BLTAPTL. 

BLTCPT&BLTDPT 

These  two  register  pairs  (BLTCPTH  and  BLTCPTL, 
BLTDPTH  and  BLTDPTL)  must  be  initialized  with  the 
start  address  of  the  line.  This  is  the  address  of  the  word 
in  which  the  start  point  of  the  line  is  located. 


889 


11.  The  A3000  Hardware 


BLTAMOD        The  value  of  the  expression 
be  stored  in  BLTAMOD. 

BLTBMOD        "2*Sdelta" 


"2*Sdelta-2*Ldelta"  must 


BLTCMOD  &  BLTDMOD 

The  width  of  the  entire  picture  in  which  the  line  is  to  be 
drawn  must  be  stored  in  these  two  modulo  registers.  As 
usual,  this  takes  the  form  of  an  even  number  of  bytes. 
With  a  normal  bit-plane  of  320  pixels  (40  bytes)  in  the 
X  direction,  the  value  for  BLTCMOD  or  BLTDMOD 
=  40. 

BLTSIZE  The  width  (bits  0  to  5)  must  be  set  to  2.  The  height  (bits 

6  to  15)  contains  the  length  of  the  line  in  pixels.  A 
height  of  0  indicates  a  line  length  of  1024  pixels.  The 
correct  line  length  is  always  the  value  of  Ldelta. 

Drawing  a  line  is  started  by  writing  to  the  BLTSIZE 
register.  Therefore,  it  should  be  the  last  register 
initialized. 

BLTADAT         This  register  must  be  initialized  to  $8000. 

BLTBDAT  BLTBDAT  contains  the  mask  with  which  the  line  is 

drawn. 

BLTAFWM        $FFFF  is  stored  in  this  mask  register. 
BLTCON0 


Bit  no. 

Name 

Function 

15 

START3 

The  4-bit  value  START0-3  contains  the  position  of 
the  start  point 

14 

START2 

of  the  line  within  the  word 

13 

START1 

at  the  start  address  of  the  line  (BLTCPTVBLTDPT) 

12 

START0 

The  four  lower  bits  of  the  X  coordinate  of  the  start 
point 

11 

USEA  =  1 

This  combination  of  the  USEx  bits  is  necessary 

10 

USEB  =  0 

for  the  line  mode 

9 

USEC  =  1 

8 

USED  =  1 

7 

LF7 

The  LFx  bits  must  be  initialized  with  $CA 

toO 

LF0 

(D  =  aC  +  AB) 
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BLTC0N1 


Bit  no. 

Name 

Function 

15 

Texture3 

This  is  the  value  for  shifting  the  mask. 

14 

Texture2 

Normally  TextureO-3  is  set  to  StartO-3. 

13 

Texturel 

The  pattern  in  the  mask  register  BLTBDAT 

12 

TextureO 

then  starts  with  the  first  point  of  the  line. 

11-7  =  0 

Unused,  always  set  to  0. 

6 

SIGN 

If  2*Sdelta<Ldelta,  set  SIGN  to  1 . 

5 

... 

Unused,  always  set  to  0. 

4 

SUL 

These  three  bits  must  be  initialized 

3 

SUD 

with  the  SUL7SUD/AUL  code 

2 

AUL 

of  the  corresponding  octant. 

1 

SING  =  1 

Draw  lines  with  only  one  point  per  raster  line. 

0 

LINE  =  1 

Put  the  Blitter  in  line  drawing  mode. 

A  numerical  example: 

You  want  to  draw  a  line  in  a  bit-plane.  The  bit-plane  is  320  by  200  pixels 
large  and  lies  at  address  $40000.  The  starting  point  of  the  line  has  the 
coordinates  X=20  and  Y=185.  The  end  point  lies  at  X=210  and  Y=35. 
(The  coordinates  are  in  relation  to  the  upper  left  corner  of  the  bit-plane.) 
DeltaX  =  190,  DeltaY  =  150. 

1st  step:  Find  the  octant  of  the  end  point 

To  do  this,  the  three  comparisons  discussed  earlier  are  performed;  the 
result:  XI  <  X2,  Yl  >  Y2  and  DeltaX  >  DeltaY.  This  yields  octant  number 
7  and  a  value  for  the  SUD/SUL/AUL  code  of  4. 

2nd  step:  Address  of  the  starting  point 

This  is  calculated  as  follows: 

starting  address  of  bitplane  +  (number  of  lines  -  Yl  -  1)  *  bytes  per  line  + 
2*(X1/16) 

The  fractional  portion  of  the  division  is  ignored.  After  inserting  the 
values: 

$40000  +  (200-185-l)*40  +  2  =  $40232 

this  value  is  placed  in  BLTCPT  and  BLTDPT.  The  number  of  bytes  per 
line  is  also  written  to  the  BLTCMOD  and  BLTDMOD  registers. 
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3rd  step:  Starting  point  of  the  line  in  STARTO-3 
Required  calculation:  XI  AND  $F.  Numerically: 

STARTO-3  =  20  AND  $F  =  4 

4th  step:  Values  for  BLTAPTL,  BLTAMOD  andBLTBMOD 

DeltaY  <  DeltaX,  meaning  that  Sdelta  =  DeltaY  and  Ldelta  =  DeltaX. 

BLTAPTL  =  2*Sdelta-Ldelta  =  2*150-190  =  110 

BLTAMOD  =  2*Sdelta-2*Ldelta  =  2*150-2*190  =  -80 

BLTBMOD  =  2*Sdelta  =  300 

2*Sdelta>Ldelta 


Therefore  SIGN  =  0. 

5th  step:  Length  of  the  line  for  BLTS1ZE 


Length  =  Ldelta  =  DeltaX  =  190. 


The  value  of  the  BLTSIZE  register  is  calculated  from  the  usual  formula: 
Length*64  +  Width.  Width  must  always  be  set  to  2  when  drawing  lines. 
BLTSIZE  =  DeltaX*64+2  =  12162  or  $2F82. 

6th  step:  Combining  the  values  for  the  two  BLTCONx  registers 

The  START  value  must  be  stored  in  the  correct  position  in  BLTCONO,  in 
addition  to  $CA  for  the  LFx  bits  and  101 1  for  USEx.  In  our  example,  this 
results  in  $ABCA. 

BLTCON1  contains  the  code  for  the  octant  and  the  control  bits.  We 
want  to  draw  our  line  normally,  so  SING  =  0.  LINE  must  naturally  be  1 . 
SIGN  was  already  calculated  and  is  0  in  this  example.  Together  this 
makes  $0011. 

In  assembly  language  the  initialization  of  the  registers  might  look  like 
this: 


LEA  $DFF000,A5 
MOVE.L  #$40232,  BLTCPTH(A5) 
MOVE.L  #$40232,  BLTDPTH(A5) 
MOVE.W  #40,  BLTCMOD(A5) 
MOVE.W  #40,  BLTDMOD(A5) 
MOVE.W  #110,  BLTAPTL(A5) 


,-Base  address  of  the  custom  chips  to  A5 

; Start  address  to  BLTCPT 

;and  BLTDPT 

; Width  of  bitplane  to  BLTCMOD 

;and  BLTDMOD 
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MOVE.W  #-80,    BLTAMOD(A5) 
MOVE.W   #300,    BLTBMOD(A5) 
MOVE.W   #$ABCA,    BLTCON0(A5) 
MOVE.W    #$11,     BLTCONKA5) 

MOVE.W  #12162,  BLTSIZE(A5)      ;Now  the  blitter  starts 

; drawing  the  line 

Other  drawing  modes 


Up  to  now  we  always  used  $CA  as  the  value  for  the  LFx  bits.  This 
causes  the  points  on  the  line  to  be  set  or  cleared  according  to  the  mask, 
while  the  other  points  remain  unchanged. 

But  other  combinations  of  LFx  are  also  useful.  To  understand  this,  you 
must  know  how  the  LFx  bits  are  interpreted  in  the  line  mode: 

The  Blitter  can  only  address  memory  by  words.  In  line  mode  the  input 
data  enters  the  Blitter  through  source  channel  C.  The  mask  is  stored  in 
the  B  register.  The  A  register  determines  which  point  in  the  word  read  is 
the  line  point.  It  always  contains  exactly  one  set  bit,  which  is  shifted  by 
the  Blitter  to  the  correct  position.  The  normal  LFx  value  of  $CA  causes 
all  bits,  for  which  the  A  bit  is  0,  to  be  taken  directly  from  source  C. 
However,  if  A  is  1,  the  destination  bit  is  taken  from  the  corresponding 
mask  bit. 

If  you  know  how  the  LFx  bits  are  used,  you  can  choose  other  drawing 
modes.  For  example,  $4A  causes  all  the  line  points  to  be  inverted. 

The  Blitter  DMA  cycles 

As  we  explained  in  the  section  on  fundamentals,  the  Blitter  uses  only 
even  bus  cycles.  Since  it  has  priority  over  the  68030,  it  is  interesting  to 
know  how  many  cycles  are  left  for  the  processor.  This  depends  on  the 
number  of  active  Blitter  DMA  channels  (A,  B,  C  and  D).  The  following 
table  shows  the  course  of  a  Blitter  operation  for  all  fifteen  possible 
combinations  of  active  and  inactive  Blitter  DMA  channels.  The  letters  A, 
B,  C  and  D  represent  the  corresponding  DMA  channels.  Behind  them, 
the  digit  1  represents  the  first  data  word  of  the  Blitter  operation,  the  digit 
3  for  the  last  word,  and  the  digit  2  for  all  words  in  between.  A  dashed 
line  (--)  indicates  that  this  bus  cycle  is  not  used  by  the  Blitter. 

Usage  of  even  bus  cycles  by  the  Blitter: 
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Comments: 

The  table  is  only  valid  if  the  following  conditions  are  fulfilled: 

1.  The  Blitter  is  not  disturbed  by  Copper  or  bit-plane  DMA  accesses. 

2.  The  Blitter  is  running  in  normal  mode  (neither  drawing  lines  nor 
filling  surfaces). 

3.  The  BLITPRI  bit  in  the  DMACON  register  is  set  and  the  Blitter  has 
absolute  priority  over  the  68030. 


Active  DMA  channels    Usage  of  even  bus  cycles 


None 


B 
B 
B 

A 
A 
A 
A 
A 
A 
A 
A 


C 
C 

D 
C 
C 


DO  --  Dl  --  D2  —  --  --  --  --  —  --  — 

CO  —  CI  —  C2  --  --  --  —  —  —  —  — 

CO  --  --  CI  DO  --  C2  Dl  —  D2  --  —  — 

BO  --  —  Bl  —  —  B2  --  --  —  --  --  -- 

BO  --  --  Bl  DO  --  B2  Dl  --  D2  --  --  -- 

BO  CO  --  Bl  CI  --  B2  C2  --  --  --  --  -- 

BO  CO  --  --  Bl  CI  DO  --  B2  C2  Dl  —  D2 

AO  --  Al  --  A2  --  -- —  —  — 

AO  --  Al  DO  A2  Dl  —  D2  —  —  --  --  — 

AO  CO  Al  CI  A2  C2  — 

AO  CO  --  Al  CI  DO  A2  C2  Dl  —  D2  —  — 

AO  BO  —  Al  Bl  --  A2  B2  —  --  —  —  — 

AO  BO  --  Al  Bl  DO  A2  B2  Dl  --  D2  --  -- 

AO  BO  CO  Al  Bl  CI  A2  B2  C3  --  —  —  -- 

AO  BO  CO  --  Al  Bl  CI  DO  A2  B2  B3  Dl  D2 


Explanations: 

As  you  can  see,  the  output  data  DO  doesn't  get  to  RAM  until  the  Al,  Bl 
and  CI  data  have  been  read.  This  results  from  the  pipelining  in  the 
Blitter.  Pipelining  means  that  the  data  is  processed  in  multiple  stages  in 
the  Blitter.  Each  stage  is  connected  to  the  output  of  the  preceding  one 
and  the  input  of  the  next.  The  first  stage  gets  the  input  data  (for  example, 
AO,  BO  and  CO),  processes  it  and  passes  it  on  to  the  second  stage.  While 
it  is  being  further  processed  in  that  stage,  the  next  input  data  is  fed  into 
the  input  stage  (Al,  Bl  and  CI).  When  the  first  data  reaches  the  output 
stage,  the  Blitter  has  long  since  read  the  next  data.  Two  data  pairs  are 
always  at  different  processing  stages  in  the  Blitter  at  any  given  time 
during  a  Blitter  operation. 

The  table  also  allows  the  processing  time  of  a  Blitter  operation  to  be 
calculated.  Every  microsecond  the  Blitter  has  two  bus  cycles  available.  If 
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it's  moving  a  64K  block  (32768  words)  from  A  to  D,  it  needs  2*32768 
cycles.  But  if  the  same  block  is  combined  with  source  C,  a  total  of 
3*32768  cycles  are  needed,  because  two  input  words  must  be  read  for 
each  output  word  produced. 

The  table  also  shows  that  the  Blitter  is  not  capable  of  using  every  bus 
cycle  even  if  only  one  DMA  channel  is  active. 

Sample  programs 

Program  1:  Drawing  lines  with  the  Blitter 

This  program  can  be  used  as  a  universal  routine  for  drawing  lines  with 
the  Blitter.  It  shows  how  the  necessary  values  can  be  calculated.  The 
program  is  quite  simple: 

At  the  start  of  the  program  the  memory  is  requested  and  the  Copper  list  is 
constructed.  The  only  new  part  is  the  OwnBlitter  routine.  As  its  name 
indicates,  it  can  be  used  to  gain  control  of  the  Blitter.  Correspondingly, 
there  is  a  call  to  DisownBlitter  at  the  end  of  the  program  so  that  the 
Blitter  returns  to  the  control  of  the  operating  system. 

The  program  uses  only  one  hi-res  bit-plane,  with  standard  dimensions  of 
640  x  256  pixels.  In  the  main  loop,  the  program  draws  lines  that  go  from 
one  side  of  the  screen  through  the  center  of  the  screen  to  the  other  side. 
When  a  screen  has  been  filled  in  this  manner,  the  program  shifts  the  mask 
used  to  draw  the  lines  and  starts  over  again. 

Comments: 

The  coordinate  specifications  in  the  program  start  from  point  0,0  in  the 
upper  left  corner  of  the  screen  and  are  not  mathematical  coordinates,  as 
were  used  in  the  previous  discussions.  This  means  that  when  comparing 
the  Y  values,  the  greater/less  than  sign  is  reversed. 

;***  Lines  with  the  Blitter 
; Custom  chip  register 


INTENA   =  $9A 
DMACON  =  $96 
DMACONR  =  $2 
COLOR00  =  $180 


Interrupt  enable  register  (write) 
DMA-Control  register  (write) 
DMA-Control  register  (read) 
Color  palette  register 
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VHPOSR   =  $6 


; Pos  i  t  ion  ( r ead ) 


;Copper  Register 

C0P1LC   =  $80  ; Address  of  1st.  Copper-List 

COP2LC   =  $84  ;Adderss  of  2nd.  Copper-List 

C0PJMP1  =  $88  ;Jump  to   Copper-List  1 

C0PJMP2  =  $8a  ;Jump  to  Copper-List  2 

;Bitplane  Register 


BPLCON0 

= 

$100 

BPLCON1 

= 

$102 

BPLCON2 

= 

$104 

BPL1PTH 

= 

$0EO 

BPL1PTL 

= 

$0E2 

BPL1MOD 

= 

$108 

BPL2MOD 

= 

$10A 

DIWSTRT 

= 

$08E 

DIWSTOP 

= 

$090 

DDFSTRT 

= 

$092 

DDFSTOP 

= 

$094 

Bitplane  control  register  0 

1  (Scroll  value) 

2  (SpriteoPlayfield  Priority) 
Pointer  to  1st .  bitplane 

Modulo  value  for  odd  Bit-Planes 
Modulo  value  for  even  Bit-Planes 
Start  of  screen  window 
End  of  screen  window 
Bit-Plane  DMA  Start 
Bit-Plane  DMA  Stop 


;Blitter  Register 


BLTCON0 

= 

$40 

BLTC0N1 

= 

$42 

BLTCPTH 

= 

$48 

BLTCPTL 

= 

$4a 

BLTBPTH 

= 

$4c 

BLTBPTL 

= 

$4e 

;Blitter  control  register 
;Blitter  control  register 
; Pointer  to  source  C 


(Pointer  to  source  B 


0  (ShiftA,Usex,LFx) 

1  (ShiftB,misc.  Bits) 


BLTAPTH  =  $50    ; Pointer  to  source  A 
BLTAPTL  =  $52 


BLTDPTH 

= 

$54 

BLTDPTL 

= 

$56 

BLTCMOD 

= 

$60 

BLTBMOD 

= 

$62 

BLTAMOD 

= 

$64 

BLTDMOD 

= 

$66 

BLTSIZE 

= 

$58 

BLTCDAT 

= 

$70 

BLTBDAT 

= 

$72 

BLTADAT 

= 

$74 

BLTAFWM 

= 

$44 

.•Pointer  to  target  data  D 


;Modulo  value  for  source  C 

;Modulo  value  for  source  B 

;Modulo  value  for  source  A 

;Modulo  value  for  target  D 

;HBlitter  window  width/height 

; Source  C  data  register 

/Source  B  data  register 

;Source  A  data  register 

;Mask  for  first  data  word  from  source  A 
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BLTALWM  =  $46    ;Mask  for  first  data  word  from  source  B 

;CIA-A  Port  register  A  (Mouse  key) 

CIAAPRA  =  $bfe001 

;Exec  Library  Base  Offsets 

OpenLibrary  =  -30-522  ;LibName,Version/al,dO 

Forbid  =  -30-102 

Permit  =  -30-108 

AllocMem  =  -30-168  ;ByteSize, Requirements/d0,dl 

FreeMem  =  -30-180  ;MemoryBlock, ByteSize/al,d0 

/Graphics  Library  Base  Offsets 

OwnBlitter    =  -30-426 
DisownBlitter  =  -30-432 

; graphics  base 

StartList  =  38 

; other  Labels 


Execbase   =  4 
Planesize   =  80*200 
Planewidth  =  80 


;Bitplane  size:  80  Bytes  by  200  lines 


CLsize     =  3*4 

Chip       =  2 

Clear      =  Chip+$10000  ,-Clear  Chip-RAM  first 


;The  Copper-List  contains  3  commands 
/allocate  Chip-RAM 


;***  Initialization  *** 

Start : 

;A;llocate  memory  for  bit  plane 

move.l  Execbase, a6 

move.l  #Planesize,d0  ;Memory  requirement  for  bit  plane 

move.l  #clear,dl 

jsr    AllocMem (a6)  ; Allocate  memory 

move .1  dO , Planeadr 

beq    Ende  ; Error  I  ->  End 
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/Allocate  memory  for  Copper-List 


moveq  #Clsize,dO 
moveq  #chip,dl 
jsr    AllocMem(a6) 
move .1  dO , CLadr 
beq    FreePlane 


; Error!  ->  FreePlane 


; Create  Copper-List 


move.l  dO,aO 

move . 1  Planeadr , dO 


.•Address  of  Copper-List  from  aO 

/Address  of  Bitplane 
move.w  tbpllpth, (a0)+   ; First  Copper  command  in  RAM 
swap   dO 

move.w  dO, (a0)+         ;Hi-Word  of  Bit  plane  address  in  RAM 
move.w  #bpllptl, (a0)+    ; second  command  in  RAM 
swap   dO 

move.w  dO,(aO)+         ;Lo-Word  of   Bitplane  address  in  RAM 
move.l  #$fffffffe, (aO)   ;End  of  Copper-List 

.•Allocate  Blitter 


move . 1  #GRname , al 

clr.l  dO 

jsr    OpenLibrary (a6) 

move.l  a6,-(sp) 

move.l  d0,a6 

move.l  a6,-(sp) 

jsr    OwnBlitter (a6) 


;ExecBase  from  the  Stack 
;GraphicsBase  from  a6 
;and  from  the  Stack 
;Take  over  Blitter 


;***  Main  program  *** 

;DMA  and  Task-Switching  off 


move.l  4 (sp) ,a6 

jsr  forbid (a6) 

lea  $dff000,a5 

move.w  #$03e0,dmacon(a5) 

;Copper  initialization 

move . 1  CLadr , copl lc ( a5 ) 

clr.w  copjmpl(a5) 


;ExecBase  to  a6 

; Task-Switching  off 


;Set  color 
move.w  #$0000,color00 (a5)    ; Black  background 
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move.w  #$OfaO,colorOO+2(a5)  ;Yellow  line 


;Playfield  initialization 


move.w  #$2081#diwstrt(a5)    ;20,129 

move.w  #$20cl,diwstop(a5)    ;20,449 

move.w  #$003c,ddfstrt(a5)    .-Normal 

move.w  #$00d4,ddfstop(a5) 

move.w  #%1001001000000000,bplcon0(a5) 

clr.w  bplconl(a5) 

clr.w  bplcon2(a5) 

clr.w  bpllmod(a5) 

clr.w  bpl2mod(a5) 


Hires  Screen 


;DMA  on 
move.w  #$83C0,dmacon(a5) 

;Draw  lines 

; Determine  start  values: 


move . 1  Planeadr , aO 
move.w  #Planewidth,al 
move.w  #255, a3 
move.w  #639, a4 
move.w  #$0303, d7 


;Constant  parameter  for  DrawLine 

; into  correct  register 

;Size  of  Bitplane  in  Register 

; Start  pattern 


Loop:   rol.w  #2,d7 
move.w  d7,a2 


; Shift  pattern 

.•Pattern  in  register  for  DrawLine 


clr.w  d6 
LoopX : 


/Clear  loop  variable 


clr.w  dl 
move.w  a3,d3 
move.w  d6,d0 
move.w  a4,d2 
sub.w  d6,d2 


Yl  =  0 

Y2  =  255 

XI  =  Loop  variable 

;X2  =  639-Loop  variable 


bsr  DrawLine 


addq.w  #4,d6 
cmp.w  a4,d6 
ble . s   LoopX 


.•Increment  loop  variable 
;Test  if  greater  than  639 
;if  not.  continue  loop 


clr.w  d6 
LoopY : 


.•Clear  loop  variable 
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move.w  a4,d0  ;X1  =  639 

clr.w  d2  ;X2  =  0 

move.w  d6,dl  ;Y1  =  loop  variable 

move.w  a3,d3 

sub.w  d6,d3  ;Y2  =  255-loop  variable 

bsr  DrawLine  ;Draw  line 

addq.w  #2,d6  /Increment  loop  variable 

cmp.w  a3,d6  ;Is  loop  variable  greater  than  255? 

ble.s   LoopY  ;if  not,  continue  loop 

btst   #6,ciaapra      ;Mouse  key  pressed? 
bne    Loop  ;No,  continue 

;***  End  program  *** 
;Wait  till  blitter  is  ready- 
Wait:   btst  #14,dmaconr (a5) 
bne    Wait 

/Activate  old  Copper-List 

move.l  (sp)+,a6       ;Get  GraphicsBase  from  Stack 

move.l  StartList (a6) ,copllc(a5) 

clr.w  copjmpl(a5)     /Activate  Startup-Copper-List 

move.w  #$8020,dmacon(a5) 

jsr    DisownBlitter (a6)     /Release  blitter 

move.l  (sp)+,a6         ;ExecBase  from  Stack 

jsr    Permit  (a6)       /Task  Switching  on 

/Release  memory  for  Copper-List 

move.l  CLadr.al         /Set  parameter  for  FreeMem 

moveq  #CLsize,dO 

jsr    FreeMem(a6)      /Release  memory 

/Release  Bitplane  memory 

FreePlane : 

move.l  Planeadr,al 
move.l  #Planesize,dO 
jsr    FreeMem (a6) 

Ende: 


900 


11.7  Programming  the  Hardware 


clr.l  dO 
rts 


; Program  end 


.•Variables 


CLadr:     del  0 
Planeadr :  dc . 1  0 


/Address  of  Copper-List 
; Address  of  Bitplane 


/Constants 


GRname:  dc.b  "graphics. library", 0 


align 


;  even 


;***  DrawLine  Routine  *** 


DrawLine  draws  a  line  with  the  Blitter. 

The  following  parameters  are  used: 

dO   =  XI   X-coordinate  of  Start  points 

dl  =  Yl   Y-coordinate  of  Start  points 

62     =  X2   X-coordinate  of  End  points 

d3   =  Y2   Y-coordinate  of  End  points 

aO  must  point  to  the  first  word  of  the  bitplane 

al  contains  bitplane  width  in  bytes 

a2  word  written  directly  to  mask  register 

d4  to  d6  are  used  as  work  registers 


DrawLine : 


/Compute  the  lines  starting  address 


move . 1 

al,d4 

mulu 

dl,d4 

moveq 

#-$10, 

d5 

and.w 

d0,d5 

lsr.w 

#3,d5 

add.w 

d5,d4 

add.l 

a0,d4 

/Width  in  work  register 

/Yl  *  Bytes  per  line 

/No  leading  characters:  $f0 

/Bottom  four  bits  masked  from  XI 

/Remainder  divided  by  8 

/Yl  *  Bytes  per  line  +  Xl/8 

/plus  starting  address  of  the  Bitplane 

/d4  now  contains  the  starting  address 

/of  the  line 

/Compute  octants  and  deltas 


clr.l  d5 
sub.w  dl,d3 
roxl.b  #l,d5 
tst.w  d3 
bge.s  y2gyl 


/Clear  work  register 

/Y2-Y1  DeltaY  from  D3 

/shift  leading  char  from  DeltaY  in  d5 

/Restore  N-Flag 

/When  DeltaY  positive,  goto  y2gyl 
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neg.w 

d3 

y2gyl: 

sub.w 

d0,d2 

roxl .  b 

#l,d5 

tst  .w 

d2 

bge.s 

x2gxl 

neg.w 

d2 

x2gxl : 

move.w 

d3,dl 

sub.w 

d2,dl 

bge.s 

dygdx 

exg 

d2,d3 

dygdx: 

roxl.b  #l,d5 

;DeltaY  invert  (if  not  positive) 

;X2-X1   DeltaX  to  D2 

;Move  leading  char  in  DeltaX  to  d5 

/Restore  N-Flag 

;When  DeltaX  positive,  goto  x2gxl 

; DeltaX  invert  (if  not   positive) 


;DeltaY  to  dl 

;DeltaY-DeltaX 

;When  DeltaY  >  DeltaX,  goto  dygdx 

.•Smaller  Delta  goto  d2 

;d5  contains  results  of  3  comparisons 
move.b  0ctant_table(pc,d5) ,d5  ;get  matching  octants 
add.w  d2,d2  ; Smaller  Delta  *  2 

;Test,  for  end  of  last  blitter  operation 

WBlit:    btst  #14,dmaconr(a5) ;BBUSY-Bit  test 
bne.s   WBlit  ;Wait  until  equal  to  0 

move.w  d2,bltbmod(a5)  ;2*  smaller  Delta  to  BLTBMOD 

sub.w  d3,d2  ;2*  smaller  Delta  -  larger  Delta 

bge.s   signnl  ;When  2*  small  delta  >  large  delta  to  signal 

or.b   #$40,d5  ;Sign  flag  set 
signnl:  move.w  d2,bltaptl (a5)  ;2*small  delta-large  delta  in  BLTAPTL 

sub.w  d3,d2  ;2*  smaller  Delta  -  2*  larger  Delta 

move.w  d2,bltamod(a5)  ;to  BLTAMOD 

.•Initialization  other  info 


move.w  #$8000,bltadat(a5) 
move.w  a2,bltbdat (a5)  ; 
move.w  #$ff f f ,bltafwm(a5) 
and.w  #$000f,d0  ; 
ror.w  #4,d0  ; 

or.w  #$0bca,d0  ; 
move.w  dO,bltconO (a5) 
move.w  d5,bltconl(a5)  ; 
move.l  d4,bltcpth(a5)  ; 
move.l  d4,bltdpth(a5) 
move.w  al,bltcmod(a5)  ; 
move.w  al,bltdmod(a5)    ; 


Mask  from  a2  in  BLTBDAT 

bottom  4  Bits  from  XI 
to  STARTO-3 
USEx  and  LFx  set 

Octant  in  Blitter 

Start  address  of  line  to 

BLTCPT  and  BLTDPT 

Width  of  Bitplane  in  both 

Modulo  Registers 


,-BLTSIZE  initialization  and  Blitter  start 


lsl.w     #6,d3 


; LENGTH   *    64 
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addq.w  #2,d3  ;plus  (Width  =  2) 

move.w  d3,bltsize(a5) 

rts 

,-Octant  table  with  LINE  =1: 

;The  octant  table  contains  code  values 

;for  each  octant,  shifted  to  the  correct  position 


Octant_table : 

dc.b  0 

*4+l 

;yl<y2. 

xl<x2 , 

dx<dy  =  0kt6 

dc.b  4 

*4+l 

;yl<y2, 

xl<x2. 

dx>dy  =  0kt7 

dc.b  2 

*4+l 

;yi<y2, 

xl>x2 , 

dx<dy  =  0kt5 

dc.b  5 

*4+l 

;yl<y2, 

xl>x2 , 

dx>dy  =  0kt4 

dc.b  1 

*4+l 

;yl>y2, 

xl<x2, 

dx<dy  =  Oktl 

dc.b  6 

*4+l 

;yl>y2, 

xl<x2 , 

dx>dy  =  OktO 

dc.b  3 

*4+l 

;yl>y2, 

xl>x2, 

dx<dy  =  0kt2 

dc.b  7 

*4+l 

;yl>y2, 

xl>x2 , 

dx>dy  =  0kt3 

end 


Program  2:  Filling  surfaces  with  the  Blitter 

This  program  is  very  similar  to  the  first  program.  It  shows  how  you  can 
create  colored  polygons  by  drawing  border  lines  and  filling  them  with 
the  Blitter.  Since  most  of  it  is  identical  to  the  first  program,  we've  only 
printed  the  parts  that  must  be  changed  in  program  1  to  create  program  2. 
The  first  part  that  must  be  changed  starts  at  the  comment  "Draw  lines 
***"  and  ends  at  the  comment  "***  End  program  ***."  This  area  must 
be  replaced  by  the  section  in  the  following  listing  labeled  "Part  1." 

Also,  the  old  octant  table  at  the  end  of  the  program  must  be  replaced 
with  the  new  one  following  the  heading  "Part  2."  The  new  octant  table  is 
required  because,  when  filling  surfaces,  the  Blitter  needs  boundary  lines 
with  only  one  pixel  per  line.  In  the  new  octant  table,  the  LINE  bit  and 
the  SING  bit  are  set. 

The  program  labeled  "Part  1"  draws  two  lines  and  then  fills  the  area 
between  them  with  the  Blitter.  Then  it  waits  for  the  mouse  button  to  be 
clicked. 


903 


11.  The  A3000  Hardware 


;***  Filling  surfaces  with  the  blitter  *** 

;Part  1: 

;Draw  filled  triangle 

;Set  starting  value 


;Draw  line 


move.l  Planeadr,aO 
move.w  #Planewidth,al 
move.w  #$ffff,a2 

;*  Draw  border  lines  * 

;Line  from  320,10  to  600,200 

move.w  #320, dO 

move.w  #10, dl 

move.w  #600, d2 

move.w  #200, d3 

bsr . L  drawl ine 

;Line  from  319,10  to  40,200 

move.w  #319,d0 

move.w  #10, dl 

move.w  #40, d2 

move.w  #200, d3 

bsr.L  drawline  ,-Draw  line 

;*  Fill  surface  * 

;Wait  until  blitter  has  drawn  last  line 

Wline:  btst  #14,dmaconr (a5)  ;Test  BBUSY 

bne.S  Wline 


;Set  constant  parameters  for 

;the  LineDraw  routine 

,-Mask  to  $FFFF  ->  no  pattern 


add.l  #Planesize-2,a0 
move.w  #$09f0,bltcon0(a5) 
move.w  #$000a,bltconl(a5) 
move.w  #$f fff ,bltafwm(a5) 
move.w  #$ffff ,bltalwm(a5) 
move.l  a0,bltapth(a5) 
move.l  a0,bltdpth(a5) 
move.w  #0,bltamod(a5) 
move.w  #0,bltdmod(a5) 
move.w  #$ff*64+40,bltsize(a5) 

;Wait  for  mouse  button 


; Address  of  last  word 

;USEA  and  D,  LFx:  D  =  A 

; Inclusive  Fill  plus  Descending 

;Set  first  and  last  word  mask 

/Address  of  last  word  of  bit- 
;plane  to  address  register 
;No  modulo 

; Start  blitter 
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end:   btst  #6,ciaapra 
bne.S  end 

;End  of  Part  1. 


;Mouse  button  pressed? 
;No  ->  continue 


;Part  2: 

; Octant  table  with  SING  =1  and  LINE  =1 : 

Octanttable : 


dc.b 

0 

*4+3 

;yl<y2, 

xl<x2 , 

dx<dy  =  Oct 6 

dc.b 

4 

*4+3 

;yl<y2, 

xl<x2 , 

dx>dy  =  0ct7 

dc.b 

2 

*4+3 

;yl<y2, 

xl>x2, 

dx<dy  =  Oct 5 

dc.b 

5 

*4+3 

;yl<y2, 

xl>x2 , 

dx>dy  =  Oct 4 

dc.b 

1 

*4+3 

;yl>y2, 

xl<x2 , 

dx<dy  =  Octl 

dc.b 

6 

*4+3 

;yl>y2, 

xl<x2 , 

dx>dy  =  OctO 

dc.b  3  *4+3  ;yl>y2,  xl>x2,  dx<dy  =  Oct2 
dc.b  7  *4+3  ;yl>y2,  xl>x2,  dx>dy  =  Oct3 

11.7.9        Sound  Output 

Fundamentals  of  electronic  music 


All  sounds,  whether  music,  noise  or  speech,  occur  in  the  form  of 
oscillations  in  the  air;  these  are  the  sound  waves  that  reach  our  ears.  A 
normal  musical  instrument  creates  these  oscillations  either  directly,  in 
which  the  air  blown  through  it  is  made  to  oscillate  (e.g.,  a  flute)  or 
indirectly,  where  part  of  the  instrument  creates  the  tone  (oscillation)  and 
then  the  air  picks  it  up  (e.g.,  string  instruments). 

An  electronic  instrument  creates  oscillations  in  its  circuits  that 
correspond  to  the  desired  sound.  These  oscillations  aren't  audible  until 
they  are  converted  to  sound  waves  by  a  loud-speaker.  On  the  Amiga  the 
speaker  built  into  the  monitor  is  normally  used.  Unfortunately,  because  of 
its  size  and  quality,  it  is  not  capable  of  high-fidelity  translation  of  the 
electrical  oscillations  into  sound  waves.  Therefore,  you  should  connect 
your  Amiga  to  a  good  amplifier/speaker  system  to  get  the  full  effect  of  its 
musical  capabilities.  What  parameters  determine  the  sound  that  comes 
from  the  computer? 
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Frequency 

The  first  is  the  frequency  of  a  sound.  It  determines  whether  the  pitch 
sounds  high  or  low.  The  frequency  is  actually  the  number  of  oscillations 
per  second,  measured  in  Hertz  (Hz).  One  oscillation  per  second  is  1  Hz, 
and  a  kilohertz  is  1000  Hz.  The  human  ear  can  discern  sounds  between 
16  and  16000  Hz.  Those  who  know  something  about  music  know  that 
the  standard  A  has  a  frequency  of  440  Hz.  The  connection  between 
frequency  and  pitch  is  as  follows:  With  each  octave  the  frequency 
doubles.  The  next  higher  A  has  a  frequency  of  880  Hz,  while  the  A  on 
the  octave  below  the  standard  has  a  frequency  of  220  Hz. 

The  frequency  of  a  tone  does  not  have  to  be  constant.  For  example,  it 
can  periodically  vary  around  the  actual  pitch  by  a  few  Hz,  creating  an 
effect  called  vibrato. 

Volume 

The  second  parameter  of  a  sound  is  its  volume.  By  volume  we  mean  the 
amplitude  of  the  oscillation.  The  volume  of  a  sound  is  measured  in 
deciBels  (dB).  The  range  of  human  hearing  is  about  ldB  to  120  dB.  Each 
increase  of  about  10  dB  doubles  the  audible  volume.  The  volume  of 
sound  is  also  called  sound  pressure  or  intensity. 

The  volume  can  be  influenced  by  many  parameters.  The  simplest  is 
naturally  the  volume  control  on  the  monitor  or  amplifier.  This  simply 
changes  the  amplitude  of  the  electrical  oscillations.  But  the  distance 
between  the  listener  and  the  speaker  also  has  an  effect  on  the  volume. 
The  farther  you  are  from  the  speaker,  the  softer  the  sound  becomes. 

Also,  the  furnishings  in  the  room,  open  or  closed  doors,  etc.  can  also 
affect  the  amplitude  of  sound  waves.  Therefore,  the  absolute  volume  is 
not  that  important.  More  interesting  is  the  relative  volume  of  sounds 
between  each  other,  such  as  whether  a  sound  is  louder  or  softer  then  its 
predecessor. 

There  is  a  relationship  between  the  volume  of  a  sound  and  its  frequency. 
The  cause  of  this  is  the  sensitivity  of  the  human  ear.  High  and  low 
sounds  are  perceived  as  being  softer  than  those  in  the  middle  range,  even 
if  they  physically  have  the  same  sound  pressure  in  deciBels.  This  middle 
pitch  range  runs  from  about  1000  to  3000  Hz.  The  oscillations  of  human 
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speech  fall  within  this  frequency  range,  which  is  probably  the  reason  for 
the  higher  sensitivity. 

The  volume  of  a  sound  can  also  change  periodically  within  a  given 
range.  This  effect  is  called  tremolo.  However,  there  is  the  variation  in 
volume  from  the  start  to  the  end  of  a  sound.  A  sound  can  start  out  loud 
and  then  slowly  die  out.  It  can  also  start  out  loud,  then  drop  a  certain 
amount  and  stop  abruptly.  Or  it  starts  softly  and  then  slowly  becomes 
louder.  There  are  almost  no  limits  to  the  possible  combinations  here. 

Tone  color  or  timbre 

The  third  and  last  parameter  of  a  sound  is  somewhat  more  complicated. 
This  is  the  timbre  or  tone  color,  and  it  plays  an  important  role.  There  are 
hundreds  of  different  instruments  which  can  all  play  a  sound  with  the 
same  frequency  and  volume,  but  still  they  sound  different  from  one 
another.  The  reason  for  this  lies  in  the  shape  of  the  oscillation.  The 
following  figure  shows  four  common  waveforms.  Why  do  they  sound 
different? 

Each  waveform,  regardless  of  what  it  looks  like,  can  be  represented  as  a 
mix  of  sine  waves  of  different  frequencies  having  a  fixed  relationship  to 
each  other.  For  a  square  wave,  the  first  wave  (or  harmonic)  has  the 
fundamental  frequency  of  the  sound,  the  second  harmonic  has  three 
times  the  fundamental  frequency  but  only  a  third  of  the  amplitude.  The 
third  harmonic  has  five  times  the  frequency  but  a  fifth  of  the  amplitude, 
and  so  on. 
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Sine 


Square 


Triangle 


Sawtooth 


Noise 


Waveforms 

The  next  figure  shows  this  for  a  square  wave  and  a  sawtooth  wave.  For 
the  sake  of  simplicity  only  the  first  three  harmonics  of  each  waveform  are 
shown. 

As  we  said,  all  periodic  waveforms  can  be  represented  as  sums  of  sine 
waves.  This  is  called  the  harmonic  series  of  a  sound.  The  pure  sine  wave 
consists  only  of  the  fundamental  frequency.  A  square  wave  consists  of 
an  infinite  number  of  harmonics.  The  number  of  harmonics  and  their 
frequency  and  amplitude  relationship  determine  the  timbre  of  a  sound. 

The  harmonic  series  is  important  because  the  human  ear  reacts  only  to 
sine  waves.  A  sound  whose  waveform  deviates  from  a  pure  sine  wave  is 
divided  into  its  harmonics  by  the  ear.  You  should  keep  these  facts  in 
mind  when  reading  the  following  discussion. 
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3  combined  sine  waves  make  a  square  wave 


v=sin  X+  sin  3x    £Jn_5x. 
1  3  5 


.or  a  sawtooth  wave 


y=Sin  X+  sin  2x     sjn3x, 
2  3 


Waveforms 


Noise 


In  addition  to  pitched  tones  there  are  also  noises.  While  you  can  define  a 
tone  very  precisely  and  also  create  it  electronically,  this  is  much  more 
difficult  for  noises.  They  have  neither  a  given  frequency  nor  a  defined 
amplitude  variation  and  no  actual  waveform.  They  represent  an  arbitrary 
combination  of  sound  events.  The  basis  of  many  noises  is  called  white 
noise,  which  is  a  mix  of  an  infinite  number  of  sounds  whose  frequencies 
and  phases  have  no  definite  relationship  to  each  other.  The  wind 
produces  this  sound,  for  example,  because  millions  of  air  molecules  are 
put  into  oscillation  as  they  collide  with  one  another  or  with  objects  on 
the  earth's  surface.  These  random  oscillations  make  up  an  undefinable 
mixture  of  sounds  we  know  as  the  rustling  of  wind. 
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Sound  creation  on  the  Amiga 


Digitizing  a  waveform 


127  -■ 


-128-  ► 


90  J  127  i  90  ,   0   I  -90  )   -127  '  -90 
49   117    117   49    -49   -117   -117    -49 


Digital  waveforms 

The  main  criterion  forjudging  the  acoustical  capabilities  of  a  computer  is 
its  versatility.  All  three  parameters  of  a  sound  (i.e.,  frequency,  volume  and 
timbre)  should  be  able  to  be  adjusted  independently. 

The  Amiga's  developers  tried  to  achieve  this  goal  as  nearly  as  possible. 
Not  to  be  limited  to  predefined  waveforms,  the  digital  equivalent  of  the 
desired  waveform  is  stored  in  memory  and  then  converted  to  the 
corresponding  electrical  oscillation  by  a  digital-to-analog  converter.  In 
other  words,  the  oscillation  is  digitized  and  stored  in  the  computer. 
During  output,  the  digitized  data  is  converted  back  to  analog  form  and 
sent  to  the  amplifier. 

In  order  to  convert  the  waveforms  to  a  form  understandable  to  the 
computer,  their  patterns  must  be  represented  by  numbers.  To  do  this, 
divide  one  cycle  of  the  desired  waveform  into  an  even  number  of  equal- 
sized  sections.  Begin  as  close  as  possible  to  a  point  where  the  wave 
intersects  the  X  axis.  For  each  of  the  sections,  put  the  corresponding  Y 
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value  into  memory.  This  produces  a  sequence  of  numbers  whose 
elements  represent  snapshots  of  the  wave  at  given  points  in  time.  These 
digitized  values  are  called  samples. 

On  output,  the  Amiga  converts  the  number  values  from  memory  back 
into  the  corresponding  output  voltages.  But  since  the  wave  is  divided 
into  a  limited  number  of  samples  by  the  digitization,  the  output  curve  can 
be  reconstructed  only  with  this  number  of  voltages.  This  results  in  the 
staircase  form  of  the  wave  shown  in  the  previous  figure. 

The  quality  of  sounds  reproduced  in  this  way  as  opposed  to  their  original 
waveforms  depends  essentially  on  two  quantities: 

One  is  the  resolution  of  the  digitized  signals.  This  is  the  value  range  of 
the  samples.  On  the  Amiga  this  is  eight  bits,  or  from  -128  to  +127.  Each 
input  value  can  take  one  of  256  possible  values  in  memory.  Since  the 
resolution  of  analog  signals  is  theoretically  unlimited,  but  that  of  the 
individual  samples  is  limited,  conversion  errors  result.  These  are  called 
quantization  or  rounding  errors.  When  the  input  value  lies  somewhere 
between  two  numbers  (it  doesn't  correspond  exactly  to  one  of  the  256 
digital  steps),  it  is  rounded  up  or  down.  The  maximum  possible 
quantization  error  is  1/256  of  the  digitized  value  (also  called  an  error  of  1 
LSB). 

A  factor  called  the  quantization  noise  is  tied  to  the  quantization  error.  As 
the  name  indicates,  this  reveals  itself  as  noise  matching  the  magnitude  of 
the  quantization  error. 

A  value  range  of  eight  bits  allows  moderately  good  reproduction  of  the 
original  wave.  However,  higher  resolution  is  needed  for  high-fidelity 
reproduction.  For  example,  a  CD  player  works  with  16  bits. 

The  second  parameter  for  the  quality  of  digitized  sound  is  the  sampling 
rate.  This  is  the  number  of  samples  per  second.  Naturally,  a  higher  number 
of  samples  results  in  better  reproduction.  The  sampling  rate  can  be  set 
within  certain  bounds  on  the  Amiga.  First  you  must  consider  how  many 
samples  are  used  per  digitized  cycle  of  the  waveform.  In  our  example  this 
is  16  values.  There  is  little  audible  difference  between  the  resulting 
staircase  waveform  and  a  normal  sine  signal. 
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The  output  of  the  digitized  sound 

Once  the  desired  waveform  has  been  converted  to  the  corresponding 
numbers  and  written  into  memory,  you  naturally  want  to  hear  it.  The 
Amiga  has  four  sound  channels,  which  all  work  according  to  the 
following  principle: 

A  digitized  wave  is  read  from  memory  through  DMA  and  output  through 
a  digital/analog  converter.  This  process  is  repeated  continually  so  that 
the  single  cycle  of  the  waveform  creates  a  continuous  tone.  Channels  0 
and  3  are  sent  to  the  left  stereo  channel,  while  1  and  2  are  sent  to  the 
right. 

Each  audio  channel  has  its  own  DMA  channel.  Since  the  DMA  on  the 
Amiga  is  performed  on  words,  two  samples  are  combined  into  one  data 
word.  For  this  reason  you  always  need  an  even  number  of  samples.  The 
upper  half  of  the  word  (bits  8-15)  is  always  output  before  the  lower  half 
(bits  0-7). 

The  data  list  for  our  digitized  sound  wave  (where  "Start"  is  the  starting 
address  of  the  list  in  chip  RAM)  looks  as  follows  in  memory: 


Start : 

dc.b  0,49 

; 1st  data  word, 

samples 

1  and  2 

dc.b  90,117 

;2nd  data  word. 

samples 

3  and  4 

dc.b  127,117 

;3rd  data  word, 

samples 

5  and  6 

dc.b  90,49 

;4th  data  word. 

samples 

7  and  8 

dc.b  0,-49 

;5th  data  word, 

samples 

9  and  10 

dc.b  -90,-117 

; 6th  data  word. 

samples 

11  and  12 

dc.b  -127,-117 

;7th  data  word. 

samples 

13  and  14 

dc.b  -90,-49 

;8th  data  word. 

samples 

15  and  16 

End: 

The  digital/analog  converter  requires  the  samples  to  be  stored  as  signed 
8-bit  numbers.  In  digital  technology,  they  must  appear  in  two's 
complement  form.  The  assembler  accomplishes  this  conversion  for  us,  so 
the  negative  values  can  be  written  directly  in  the  data  list. 

Now  you  must  select  one  of  the  four  channels  over  which  to  output  the 
tone.  The  corresponding  DMA  channel  must  then  be  initialized.  Five 
registers  per  channel  set  the  operating  parameters.  The  first  two  form  an 
address  register  pair,  which  you  should  recognize  from  the  other  DMA 
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channels.  They  are  called  AUDxLCH  and  AUDxLCL,  or  together 
AUDxLC,  where  x  is  the  number  of  the  DMA  channel: 


fceg. 

Name 

Function 

$0A0 

AUDOLCH 

Pointer  to  the  audio  data 

Bits  16-20 

$0A2 

AUDOLCL 

for  channel  0 

Bits  0-15 

$0B0 

AUD1LCH 

Pointer  to  the  audio  data 

Bits  16-20 

$0B2 

AUD1LCL 

for  channel  1 

Bits  0-15 

$0C0 

AUD2LCH 

Pointer  to  the  audio  data 

Bits  16-20 

$0C2 

AUD2LCL 

for  channel  2 

Bits  0-15 

$0D0 

AUD3LCH 

Pointer  to  the  audio  data 

Bits  16-20 

$0D2 

AUD3LCL 

for  channel  3 

Bits  0-15 

The  initialization  of  these  address  pointers  can  be  accomplished  with  a 
MOVE.L  command: 


LEA  $DFF000,  A5 

MOVE.L  #Start,  AUDOLCH (A5) 


;Base  address  of  custom  chips  to  A5 
;Write  "Start"  in  AUD0LC 


Next,  the  DMA  controller  must  be  told  the  length  of  the  digitized  cycle 
(i.e.,  how  many  samples  it  comprises).  The  appropriate  registers  are  the 
AUDxLEN  registers: 


re9- 

Name 

Function 

$0A4 

AUD0LEN 

Number  of  audio  data  words  for  channel  0 

$0B4 

AUD1LEN 

Number  of  audio  data  words  for  channel  1 

$0C4 

AUD2LEN 

Number  of  audio  data  words  for  channel  2 

$0D4 

AUD3LEN 

Number  of  audio  data  words  for  channel  3 

The  length  is  specified  in  words,  not  bytes.  The  number  of  bytes  must  be 
divided  by  two  before  being  written  to  the  AUDxLEN  register. 

The  AUDxLEN  register  can  be  initialized  with  the  following  MOVE 
command.  To  avoid  having  to  count  all  the  words,  two  labels  are  defined: 
"Start"  is  the  starting  address  of  the  data  list,  "End"  the  end  address+1 
(see  the  previous  example  data  list).  The  base  address  of  the  custom  chips 
($DFF00O)  is  stored  in  A5: 


MOVE.W  # (End-Start) /2,  AUD0LEN(A5) 


Now  comes  the  volume  of  the  sound.  On  the  Amiga  the  volume  for  each 
channel  can  be  set  separately.  A  total  of  65  levels  are  available,  ranging 
from  0  (inaudible)  to  64  (full  volume).  The  corresponding  registers  are 
called  AUDxVOL: 
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Reg. 


Name 


Function 


fOA8~ 
$0B8 
$0C8 
$0D8 


AUDOVOL 
AUDI  VOL 
AUD2VOL 
AUD3VOL 


Volume  of  audio  channel  0 
Volume  of  audio  channel  1 
Volume  of  audio  channel  2 
Volume  of  audio  channel  3 


Let's  set  our  audio  channel  to  half  volume: 


MOVE.W  #32,  AUD0VOL(A5) 


The  last  parameter  is  the  sampling  rate.  This  determines  how  often  a  data 
byte  (sample)  is  sent  to  the  digital/analog  converter.  The  sampling  rate 
determines  the  frequency  of  the  sound.  As  explained  initially,  the 
frequency  equals  the  number  of  oscillations  (cycles)  per  second.  An 
oscillation  consists  of  an  arbitrary  number  of  samples.  In  our  example  it  is 
16.  If  the  sampling  rate  represents  the  number  of  samples  read  per  second, 
the  frequency  of  the  sound  corresponds  to  the  sampling  rate  divided  by 
the  number  of  samples  per'cycle: 


Frequency  = 


Sampling  rate 


Samples  per  cycle 


Unfortunately  the  sampling  rate  cannot  be  specified  directly  in  Hertz. 
Instead,  the  DMA  controller  wants  to  know  the  number  of  bus  cycles 
desired  between  the  output  of  two  samples.  A  bus  cycle  takes  exactly 
279.365  nanoseconds  (billionths  of  a  second)  or  2.79365  *  10-7 
seconds. 

To  get  from  the  sampling  rate  to  the  number  of  bus  cycles,  first  take  the 
inverse  of  the  sampling  rate.  This  gives  you  the  duration  of  the  sample. 
Dividing  this  value  by  the  duration  of  a  bus  cycle  in  seconds  yields  the 
number  of  bus  cycles  between  two  samples,  called  the  sample  period: 


Sample  period  = 


Sampling  rate  *  2.79365  *  10-7 


Let's  assume  that  we  want  to  play  our  sample  tone  with  a  frequency  of 
440  Hz,  the  standard  A.  The  sampling  rate  is  computed  as  follows: 
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Sampling  rate  =  Frequency  *  Samples  per  cycle 
Sampling  rate  =  440  Hz  *  1 6  =  7040  Hz 


We  quickly  obtain  the  required  sample  period  by  inserting  the 
appropriate  values: 


Sample  period  = 


1 


=  508.4583 


7040*2.79365*10-7 


Since  only  integral  values  can  be  specified  for  the  sample  period,  we 
round  the  result  to  508.  As  a  result,  the  output  frequency  is  not  exactly 
440  Hz,  but  the  deviation  is  minimal,  namely  0.4  Hz. 

The  sample  period  can  theoretically  be  anything  between  0  and  65535. 
However,  the  actual  range  has  an  upper  limit.  As  can  be  gathered  from 
the  figure  in  the  "Fundamentals"  section,  each  audio  channel  has  one 
DMA  slot  per  raster  line  (i.e.,  one  data  word  (two  samples)  can  be  read 
from  memory  in  each  raster  line).  The  smallest  possible  value  for  the 
sample  period  is  124.  The  sample  frequency  for  this  value  is  28867  Hz.  If 
the  sample  period  is  made  shorter  than  124,  a  data  word  can  be  output 
twice  because  the  next  one  cannot  be  read  in  time. 

The  sample  period  registers  are  called  AUDxPER: 


Reg. 


Name 


|0A6 
$0B6 
$0C6 
$0D6 


Function 


AUD0PER 
AUDI PER 
AUD2PER 
AUD3PER 


Sample  period  for  audio  channel  0 
Sample  period  for  audio  channel  1 
Sample  period  for  audio  channel  2 
Sample  period  for  audio  channel  3 


MOVE.W  #508,AUD0PER(A5)  puts  the  sampling  rate  we  calculated  into 
the  AUD0PER  register.  Now  all  the  registers  for  audio  channel  0  have 
been  supplied  with  the  proper  values  for  our  sound.  To  make  it  audible, 
we  still  have  to  enable  the  DMA  access  for  audio  channel  0.  Four  bits  in 
the  DMACON  register  are  responsible  for  the  audio  DMA  channels: 
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DMACON  bit  no.      Name 


Audio  DMA  channel  no. 


3 
2 

1 
0 


AUD3EN 
AUD2EN 
AUDI  EN 
AUDOEN 


3 
2 
1 
0 


To  enable  the  audio  DMA  for  channel  0,  we  set  the  AUDOEN  bit  to  1.  To 
be  on  the  safe  side,  the  DMAEN  bit  should  be  set  along  with  it  (see 
"Fundamentals"): 


MOVE.W  #$8201,  DMACON(A5) 


;Set  AUDOEN  and  DMAEN 


Now  the  DMA  starts  to  fetch  the  audio  data  from  memory  and  output  it 
through  the  digital/analog  converter.  The  sound  can  be  heard  through 
the  speaker.  To  turn  it  off  again,  simply  set  AUDOEN  =  0. 

Whenever  AUDxEN  is  set  to  1,  the  DMA  starts  at  the  address  in 
AUDxLC.  There  is  one  exception:  If  the  DMA  channel  was  on 
(AUDxEN  =  1)  and  the  bit  is  briefly  cleared  and  then  set  back  to  1 
without  the  DMA  channel  reading  a  new  data  word  in  the  meantime,  the 
DMA  controller  continues  with  the  old  address. 

Audio  interrupts 

The  audio  DMA  always  starts  with  the  data  byte  at  the  address  in 
AUDxLC.  Once  the  number  of  data  words  specified  in  AUDxLEN  have 
been  read  from  memory  and  output,  the  DMA  starts  over  at  the  AUDxLC 
address.  In  contrast  to  the  address  registers  for  the  Blitter  or  the 
bit-planes,  the  content  of  the  AUDxLC  register  is  not  changed  during  the 
audio  DMA.  There  is  an  additional  address  register  for  each  audio 
channel.  Before  the  DMA  controller  gets  the  first  data  byte  from  memory, 
it  copies  the  value  from  the  AUDxLC  register  to  this  internal  address 
register. 

It  also  transfers  the  AUDxLEN  register  value  into  an  internal  counter. 
When  this  happens,  an  interrupt  is  generated.  As  you  may  recall  from  the 
section  on  interrupts,  there  is  a  separate  interrupt  bit  for  each  of  the  four 
audio  channels.  The  level  4  processor  interrupt  is  reserved  exclusively  for 
these  bits. 

While  the  DMA  controller  now  reads  data  words  from  memory,  the 
processor  can  supply  AUDxLC  and  AUDxLEN  with  new  data,  since  the 
values  of  both  registers  are  stored  internally.  Not  until  the  counter  that 
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was  initially  loaded  with  the  value  from  AUDxLEN  reaches  0  will  the 
data  from  AUDxLC  and  AUDxLEN  be  read  again. 

The  processor  then  has  enough  time  to  change  the  values  of  the  two 
registers,  if  necessary.  This  allows  uninterrupted  sound  output. 

An  interrupt  is  generated  after  each  complete  cycle.  This  means  that  for 
high  frequency  sounds  interrupts  occur  very  often.  The  interrupt  enable 
bits  (INTEN)  for  the  audio  interrupts  should  be  set  only  when  they  are 
actually  needed,  or  the  processor  may  not  be  able  to  save  itself  from  all 
the  interrupt  requests. 

Modulation  of  volume  and  frequency 

To  create  certain  sound  effects,  it  is  possible  to  modulate  the  frequency 
and/or  volume.  One  of  the  DMA  channels  acts  as  a  modulator  which 
changes  the  corresponding  parameters  of  another  channel.  This  can  be 
done  very  simply:  The  modulation  oscillator  fetches  its  data  from  memory 
as  usual,  but  instead  of  sending  it  to  the  digital/analog  converter,  it  writes 
it  to  the  volume  or  frequency  register  of  the  oscillator  that  it  modulates 
(AUDxVOL  or  AUDxLEN).  It  can  also  affect  both  registers  at  once.  In 
this  case  the  data  words  read  from  its  data  list  are  written  alternately  to 
the  AUDxVOL  and  AUDxLEN  registers.  The  data  words  have  the  same 
format  as  their  destination  registers: 


Volume: 
Frequency: 


Bits  7-15       Unused 

Bits  0-6        Volume  value  between  0  and  64 

Bits  0-15      Sample  period  


The  following  shows  the  use  of  data  words  of  the  modulation  oscillator 
for  all  three  possible  cases: 


Data  word 
No. 


Oscillator  modulates: 
Frequency 


Volume         Frequency  &  volume 


Period  1 
Period  2 
Period  3 
Period  4 


Volume  1 
Volume  2 
Volume  3 
Volume  4 


Volume  1 
Period  1 
Volume  2 
Period  2 


To  activate  an  audio  channel  as  a  modulator,  you  must  set  the 
corresponding  bit  or  bits  in  the  audio  disk  control  register  (ADKCON). 
Each  channel  can  modulate  only  its  successor:  channel  0  modulates 
channel  1,  channel  1  modulates  channel  2,  and  channel  2  modulates 
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channel  3.  Channel  3  can  also  be  set  as  a  modulator,  but  its  data  words 
are  not  used  to  modulate  another  channel  and  are  lost.  If  an  audio 
channel  is  used  as  a  modulator,  its  audio  output  is  disabled. 

The  ADKCON  register  contains,  as  its  name  suggests,  control  bits  for  the 
disk  controller  in  addition  to  the  audio  circuitry.  The  disk  controller  bits 
are  explained  in  more  detail  in  another  section. 


ADKCON  register  $09E  (write)  $010  (read) 


Bit  no. 

Name 

Function 

15 

14-8 

7 

6 

5 

4 

3 

SET/CLR 

USE3PN 
USE2P3 
USE1P2 
USE0P1 
USE3VN 

Bits  are  set  (SET/CLR=1)  or  cleared 

Used  by  the  disk  controller 

Audio  channel  3  modulates  nothing 

Audio  channel  2  modulates  period  of  channel  3 

Audio  channel  1  modulates  period  of  channel  2 

Audio  channel  0  modulates  period  of  channel  1 

Audio  channel  3  modulates  nothing 

2 

USE2V3 

Audio  channel  2  modulates  volume  of  channel  3 

1 

USE1V2 

Audio  channel  1  modulates  volume  of  channel  2 

0 

USE0V1 

Audio  channel  0  modulates  volume  of  channel  1 

To  recap:  If  a  channel  is  used  for  modulation,  its  data  words  are  simply 
written  into  the  corresponding  register  of  the  modulated  channel.  In 
other  respects  the  two  operate  completely  independently  of  each  other. 

Problems  of  digital  sound  generation  on  the  Amiga 

In  our  example  we  defined  a  cycle  with  16  samples.  The  maximum 
sampling  rate  is  28867  Hz.  This  yields  a  maximum  frequency  of  28867  / 
16  =  1460.4  Hz.  This  is  close  to  a  third-octave  F  sharp  (1480  Hz). 

If  you  want  to  go  higher,  you  must  decrease  the  number  of  samples  per 
cycle.  If  we  define  our  sine  with  half  the  samples,  the  maximum 
frequency  increases  to  3020.8  Hz.  However,  eight  data  bytes  aren't 
enough  for  a  good  sine  wave.  For  yet  higher  pitches,  the  number  of 
samples  decreases  even  more.  For  6041.6  Hz  there  are  only  four. 
Waveforms  can  barely  be  recognized  with  just  four  samples. 
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Digitizing  multiple  waves  for  improving 
tone  quality 


S1        S2      S3      S4        S5       S6      S7     S8 

S  =  sample 


Cycles 

However,  this  isn't  very  noticeable  when  heard.  The  ear  reacts  practically 
the  same.  The  higher  the  frequency,  the  more  difficult  it  is  to  identify 
sounds.  Despite  this,  it  can  improve  the  sound  quality  to  use  multiple 
cycles  to  define  the  desired  waveform  at  high  frequencies. 

The  maximum  frequency  of  the  Amiga  sound  output  is  limited  by  another 
factor.  When  converting  the  digital  sound  data  back  to  analog,  two 
undesired  interference  frequencies  occur  due  to  interactions  between  the 
sampling  rate  and  the  desired  sound  frequency.  One  of  these  is  the  sum 
of  the  sampling  rate  and  frequency  and  the  other  is  their  difference.  This 
phenomenon  is  called  "aliasing  distortion." 

For  example,  with  a  3  kHz  sound  and  a  12  kHz  sampling  rate,  the 
difference  is  9  kHz  and  the  sum  15  kHz. 
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The  low-pass  filter 

In  order  to  eliminate  the  alias  frequencies,  a  device  called  a  low-pass  filter 
has  been  placed  between  the  output  of  the  digital/analog  converter  and 
the  audio  connectors.  All  frequencies  up  to  4  kHz  pass  through 
undisturbed.  Between  4  and  7  kHz  the  signal  is  weakened,  until  above  7 
kHz  nothing  is  allowed  to  pass.  For  example,  the  3  kHz  tone  is  not 
affected  by  the  low-pass  filter,  but  both  the  sum  and  the  difference 
frequencies  of  9  and  15  kHz  lie  above  the  filter's  cut-off  frequency  of  7 
kHz  and  cannot  pass  through.  Also,  they  are  not  heard  through  the 
speaker.  If  you  try  to  output  the  same  3  kHz  tone  with  a  sampling  rate  of 
9  kHz,  the  difference  frequency  of  6  kHz  (9  kHz  -  3  kHz)  is  diminished 
by  the  filter  but  still  passes  through  it. 

To  be  sure  that  the  difference  frequency  always  lies  above  the  cut-off 
frequency  of  the  filter,  we  must  observe  the  following  rule: 


Sampling  rate  >  highest  frequency  component  +  7  kHz 
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It  is  not  enough  to  ensure  that  the  difference  between  the  sampling 
frequency  and  the  desired  output  frequency  is  greater  than  7  kHz.  If  a 
waveform  with  many  harmonics  is  used,  each  of  the  harmonics  produces 
its  own  difference  frequency  with  the  sampling  rate.  This  is  why  the 
highest  frequency  of  the  waveform  must  be  used  in  the  previous 
expression. 

Not  only  does  the  low-pass  filter  hold  back  the  aliasing  distortion,  it  also 
limits  the  frequency  range  of  the  Amiga.  To  be  sure,  tones  with  a 
fundamental  frequency  between  4  and  7  kHz  rarely  occur  in  a  musical 
piece,  but  the  harmonics  of  much  lower  fundamentals  for  certain 
waveforms  lie  within  this  range.  This  is  especially  clear  for  a  square  wave. 
The  square  waveform,  as  we  saw  earlier,  consists  of  the  combination  of 
several  sine  waves  having  a  set  frequency  relationship  to  each  other.  In 
the  figure  the  square  wave  is  shown  to  consist  of  just  two  harmonics  and 
the  fundamental  tone.  However,  an  actual  square  wave  has  an  infinite 
number  of  harmonics.  If  the  higher-order  harmonics  are  limited  or 
removed  by  the  filter,  a  somewhat  deformed  square  wave  results.  In  the 
extreme  case  where  the  fundamental  frequency  of  the  square  wave 
approaches  the  cut-off  frequency  of  the  filter,  only  the  fundamental 
remains.  This  turns  the  original  square  wave  into  a  sine  wave. 

Amplitude  envelope  of  a  sound 

In  addition  to  the  waveform,  the  sound  of  an  instrument  is  also 
influenced  by  its  amplitude  envelope.  The  Amiga  can  do  almost  anything 
in  the  area  of  waveforms.  How  are  specific  envelopes  programmed? 

The  envelope  of  a  sound  can  be  divided  into  three  sections:  The  attack, 
sustain,  and  decay  phases. 

As  soon  as  the  sound  is  played,  the  attack  phase  begins.  It  determines 
how  quickly  the  volume  rises  from  zero  to  the  sustain  value.  During  the 
sustain  phase  the  sound  remains  at  this  volume.  As  the  sound  ends,  it 
enters  the  decay  phase,  where  the  volume  drops  from  the  sustain  value 
back  to  zero. 

The  amplitude  curve  that  this  process  represents  is  generally  called  an 
envelope.  How  do  you  program  such  an  envelope  on  the  Amiga? 

There  are  three  possibilities: 
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Volume  modulation 

A  second  sound  channel  is  used  to  modulate  the  volume  of  the  sound. 
For  example,  channel  0  can  be  used  to  modulate  channel  1.  Channel  1 
can  continually  output  the  desired  sound  with  its  volume  set  to  0. 

The  desired  amplitude  curve  is  divided  into  two  parts:  attack  phase  and 
decay  phase.  It  is  digitized  (just  like  a  waveform)  and  placed  in  memory 
in  two  data  lists.  When  the  sound  is  to  be  played,  channel  0  is  set  to  the 
address  of  the  attack  data  and  started.  Since  it  modulates  the  volume  of 
channel  1,  the  volume  of  the  sound  follows  the  desired  attack  phase 
exactly.  When  the  attack  phase  reaches  the  sustain  value,  the  data  list  for 
channel  0  has  been  processed.  It  then  generates  an  interrupt,  and  the 
data  list  would  normally  be  processed  again  from  the  beginning.  The 
processor  must  react  to  the  interrupt  and  turn  off  channel  0  by  means  of 
the  AUDOEN  bit  in  the  DMACON  register.  Channel  1  remains  at  the 
desired  sustain  volume. 

When  the  tone  is  to  be  turned  off,  you  set  channel  0  to  the  start  of  the 
decay  data  and  start  it  again.  Wait  again  for  the  interrupt,  which  signals 
that  the  decay  phase  is  done,  and  turn  channel  0  off. 

The  registers  for  channel  0  must  be  initialized  as  follows  for  this 
procedure: 

USE0V1  This  bit  in  the  ADKCON  register  should  be  set  to  1  so 

that  channel  0  modulates  the  volume  of  channel  1. 

AUDOLC  First  set  to  the  data  list  for  the  attack  phase  and  then  to 

that  of  the  decay  phase. 

AUDOLEN  Contains,  depending  on  the  address  in  AUDOLC,  the 
length  of  either  the  attack  or  decay  data. 

AUDOVOL  Has  no  function  here,  since  the  audio  output  of  channel 
0  is  turned  off. 

AUDOPER  The  content  of  the  AUDOPER  register  determines  the 
speed  at  which  the  volume  data  is  read  from  memory. 
This  can  be  used  to  set  the  length  of  the  attack/decay 
phase. 
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This  method  allows  the  desired  envelope  to  be  constructed  perfectly. 
Unfortunately,  it  also  has  a  big  disadvantage:  Two  audio  channels  are 
required  for  one  sound.  If  you  want  four  different  sound  channels,  you 
have  to  use  an  alternate  method: 

Controlling  volume  with  the  processor 

The  desired  envelope  is  placed  in  memory  as  previously  described. 
However,  this  time  the  processor  changes  the  volume.  It  fetches  the 
current  volume  from  memory  at  regular  intervals  and  writes  it  to  the 
volume  register  of  the  corresponding  sound  channel. 

The  program  must  be  run  as  an  interrupt  routine.  This  can  be  done  in  the 
vertical  blanking  interrupt  or  one  of  the  timer  interrupts  from  CIA-B  can 
be  used. 

The  disadvantage  of  this  method  is  the  amount  of  processor  time  that  it 
requires,  since  the  volume  control  is  not  performed  by  DMA.  Since  the 
amount  of  time  needed  is  reasonably  limited,  this  is  usually  the  best 
method  for  most  applications. 

Constructing  the  envelope  in  the  sample  data 

This  method  is  best  for  short  sounds  or  sound  effects.  Instead  of 
digitizing  just  one  cycle  of  the  desired  waveform,  write  the  entire  sound 
into  memory.  A  program  can  calculate  it,  or  you  can  use  an  audio 
digitizer,  which  performs  hardware  digitizing  of  sound  with  a 
microphone  and  analog/digital  converter. 

Several  companies  offer  such  devices  for  use  with  the  Amiga.  Once  the 
data  is  in  the  Amiga,  it  can  be  played  back  at  any  pitch  or  speed.  This 
allows  complex  effects,  such  as  laughter  or  screams,  to  be  reproduced  by 
the  Amiga  with  considerable  accuracy. 

This  method  also  has  its  disadvantages:  It  involves  either  difficult 
calculations  or  additional  hardware  to  put  the  complete  sound  in 
digitized  form  into  memory.  In  addition,  this  method  requires  large 
amounts  of  memory.  For  example,  if  the  sound  is  1  second  long  with  a 
sampling  rate  of  20  kHz,  the  sound  data  takes  up  20K. 
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Tips,  tricks  and  more 

Sound  quality 

The  value  range  of  the  digital  data  is  from  -128  to  127.  This  range  should 
be  used  as  fully  as  possible.  It  is  best  when  the  amplitude  of  the  digital 
waveform  equals  256. 

Otherwise  the  sound  quality  deteriorates  audibly,  since  a  decrease  in  the 
range  means  relatively  greater  quantization  error  and  noise  that  can 
quickly  reach  distortional  proportions. 

For  this  reason  you  should  avoid  using  the  amplitude  of  the  digitized 
sound  to  control  the  volume.  Each  channel  has  its  own  AUDxVOL 
register  for  volume  control.  If  the  volume  is  reduced  with  this  register,  the 
relationship  between  the  desired  sound  and  the  distortion  remains  the 
same  and  the  Amiga's  high  sound  quality  is  preserved. 

Changing  waveforms  smoothly 

To  avoid  annoying  crackling  or  jumps  in  volume  when  changing 
waveforms,  remember  the  following  rules: 

Each  cycle  should  be  digitized  from  zero-point  to  zero-point  (i.e.,  it 
should  start  and  end  at  a  point  where  the  waveform  crosses  the  X  axis). 

If  you  follow  this  rule,  all  waveforms  in  memory  have  the  same  starting 
and  ending  value,  namely  zero.  In  transitions  between  consecutive 
waveforms  of  different  shapes,  there  are  no  sudden  level  jumps  which 
would  be  heard  as  noise. 

Secondly,  you  should  make  sure  that  the  total  volumes  of  the  two  cycles 
are  approximately  equal.  Volume  refers  to  the  effective  value  of  the 
waveform.  The  effective  value  is  equal  to  the  amplitude  of  a  square  wave 
signal  whose  surface  under  the  curve  is  exactly  as  large  as  that  of  the 
waveform. 

This  effective  value  determines  the  volume  of  an  oscillation.  Only  for  a 
square  wave  does  it  equal  the  amplitude.  If  you  change  from  one 
waveform  to  another  with  a  higher  effective  value,  the  second  sounds 
louder  than  its  predecessor. 
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The  effective  value  of  a  cycle  can  be  easily  calculated  from  its  digitized 
data: 

You  add  up  the  values  of  all  the  data  bytes  and  divide  the  result  by  the 
number  of  data  bytes. 

If  you  want  to  fully  utilize  the  8-bit  value  range  of  the  digital/analog 
converter  for  all  waveforms,  the  effective  values  will  not  always  match. 
The  volume  must  be  adjusted  accordingly  with  the  AUDxVOL  register 
when  changing  waveforms. 

Playing  notes 

Normally  a  piece  of  music  is  written  out  in  the  form  of  notes.  If  you  want 
to  play  it  on  the  Amiga,  you  must  convert  the  notes  to  the  appropriate 
sample  periods.  To  minimize  the  amount  of  calculation,  it  is  generally  best 
to  use  a  table  containing  the  sample  period  values  for  all  the  half-tones  in 
an  octave: 

Table  of  sample  period  values  for  musical  notes  (for  AUDxLEN  =  16): 


Note       Frequency  [Hz] 


Sample  period 


c 

261.7 

c# 

277.2 

D 

293.7 

D# 

311.2 

E 

329.7 

F 

349.3 

F# 

370.0 

G 

392.0 

G# 

415.3 

A 

440.0 

A# 

466.2 

B 

493.9 

C 

523.3 

427 

(262.0) 

404 

(276.9) 

381 

(293.6) 

359 

(311.6) 

339 

(330.0) 

320 

(349.6) 

302 

(370.4) 

285 

(392.5) 

269 

(415.8) 

254 

(440.4) 

240 

(466.0) 

226 

(495.0) 

214 

(522.7) 

A  value  in  parentheses  represents  the  actual  frequency  for  the 
corresponding  sampling  period.  The  frequency  of  a  half-tone  is  always 
greater  than  its  predecessor  by  the  factor  "twelfth  root  of  2."  Thus  440 
(A)  *  2(1/12)  =  466.2  (A#),  466.2  (A#)  *  2(1/12)  =  493.9  (B),  etc. 

An  octave  always  corresponds  to  a  doubling  of  frequency. 
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If  you  want  to  play  a  note  from  an  octave  that  is  not  in  the  table,  there 
are  two  options: 

1.  Change  the  sampling  period.  For  each  octave  up  the  value  must  be 
halved.  An  octave  lower  means  doubling  the  sampling  period.  This 
is  simple,  but  one  soon  runs  into  certain  limits.  With  a  data  field  of 
32  bytes  (AUDxLEN  =  16),  as  in  our  table,  the  smallest  possible 
sampling  period  (124)  is  reached  with  the  second  A.  The  data  list 
must  be  reduced  in  size. 

In  this  case  you  get  problems  with  lower  tones  since  the  aliasing 
distortion  then  becomes  audible. 

A  better  solution  is  procedure  2: 

2.  Create  a  separate  data  list  for  each  octave.  The  sampling  period 
value  remains  the  same  for  every  octave.  It  is  used  only  to  select  the 
half-tone.  If  a  tone  from  an  octave  above  that  in  the  table  is 
required,  you  use  a  data  list  that  is  only  half  as  long. 
Correspondingly,  a  list  twice  as  long  is  used  for  the  next  lower 
octave. 

The  normal  musical  range  comprises  eight  octaves,  meaning  that 
you  need  eight  data  lists  per  waveform. 

In  return  for  the  extra  work  this  method  involves,  you  always  get  the 
optimal  sound  regardless  of  pitch. 

Creating  higher  frequencies 

The  minimal  sampling  period  is  normally  124.  The  reason  for  this  is  that 
the  audio  DMA  is  not  able  to  read  the  data  words  fast  enough  to  support 
a  shorter  sampling  period.  The  old  data  word  is  then  output  more  than 
once.  This  effect  can  be  used  to  our  advantage.  Since  the  data  word  read 
contains  two  samples,  a  high  frequency  square  wave  can  be  created  with 
it.  With  a  sampling  period  of  1  you  get  a  sampling  frequency  of  3.58 
MHz  and  an  output  frequency  of  1.74  MHz.  To  be  able  to  use  this  high 
frequency  output  signal,  you  must  intercept  it  before  it  reaches  the  low- 
pass  filter.  The  AUDIN  input  (pin  16)  of  the  serial  connector  (RS232) 
allows  you  to  do  this.  It  is  connected  directly  to  the  right  audio  output  of 
Paula  (see  the  section  on  interfaces). 
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In  order  to  create  such  high  frequencies,  AUDxVOL  must  be  set  to  the 
maximum  volume  (AUDxVOL  =  64). 

Playing  polyphonic  music 

Since  the  Amiga  has  four  independent  audio  channels,  four  different 
sounds  can  be  created  at  once.  This  allows  any  four-voice  musical  pieces 
to  be  played  directly. 

But  there  can  be  more.  Just  because  there  are  four  audio  channels 
doesn't  mean  that  four  voices  is  the  maximum.  As  we  mentioned,  each 
waveform  is  actually  a  combination  of  sine  signals.  Just  as  these 
harmonics  together  make  up  the  waveform,  you  can  also  combine 
multiple  waveforms  into  a  multi-voiced  sound.  The  output  signals  for 
audio  channels  0  and  3  are  mixed  together  into  one  stereo  channel  inside 
Paula.  The  waveforms  of  both  channels  are  combined  into  a  single  two- 
voiced  channel. 

The  same  thing  that's  done  electronically  with  analog  signals  can  be 
done  by  computation  with  digital  data.  Simply  add  the  digital  data  of 
two  completely  different  waveforms  and  output  the  new  data  to  the 
audio  channel  as  usual.  Now  you  have  two  voices  per  audio  channel. 
Theoretically,  any  number  of  voices  can  be  played  over  a  sound  channel 
in  this  manner. 

In  practice  the  number  of  voices  is  limited  by  the  speed  of  computation, 
but  16  voices  are  certainly  possible. 

Calculating  the  summed  signal  from  the  components  is  very  simple.  At 
each  point  in  time  the  current  values  of  all  the  sounds  are  added  and  the 
result  is  divided  by  the  number  of  voices.  This  is  how  a  square  signal 
results  from  combining  sine  waves  with  the  right  relative  frequencies. 

Audio  output  without  DMA 

Like  all  DMA  channels,  the  audio  DMA  channels  have  registers  to  which 
they  write  data  and  where  data  can  also  be  written  by  the  processor: 
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The  audio  data  registers 


Reg. 


Name 


Function 


$0AA~ 
$0BA 
$0CA 
$0DA 


AUDODAT 
AUDI DAT 
AUD2DAT 
AUD3DAT 


These  four  registers  always  contain  the  current 
audio  data  word,  consisting  of  two  samples. 
The  sample  in  the  upper  byte  (bits  8-15) 
is  always  output  first. 


For  the  processor  to  be  able  to  write  to  the  audio  data  registers,  the  DMA 
must  be  turned  off  with  AUDxEN  =  0.  This  also  changes  the  creation  of 
audio  interrupts.  They  will  now  always  occur  after  the  output  of  the  two 
samples  in  the  AUDxDAT  register  instead  of  at  the  start  of  each  audio 
data  list. 

If  a  new  data  word  is  not  loaded  into  AUDxDAT  in  time,  the  last  two 
samples  are  not  repeated  as  they  are  for  DMA  operation,  but  the  output 
remains  at  the  value  of  the  last  data  byte  (the  lower  half  of  the  word  in 
AUDxDAT). 

The  direct  programming  of  the  audio  data  registers  costs  a  great  deal  of 
processing  time.  The  audio  DMA  should  be  used  except  in  special  cases. 

A  few  facts 

AUDxVOL  values  in  deciBels  (0  dB  =  full  volume): 


AUDxVOL 

dB 

AUDxVOL 

dB 

AUDxVOL 

dB 

AUDxVOL 

dB 

64 

0.0 

48 

-2.5 

32 

-6.0 

16 

-12.0 

63 

-0.1 

47 

-2.7 

31 

-6.3 

15 

-12.6 

62 

-0.3 

46 

-2.9 

30 

-6.6 

14 

-13.2 

61 

-0.4 

45 

-3.1 

29 

-6.9 

13 

-13.8 

60 

-0.6 

44 

-3.3 

28 

-7.2 

12 

-14.5 

59 

-0.7 

43 

-3.5 

27 

-7.5 

11 

-15.3 

58 

-0.9 

42 

-3.7 

26 

-7.8 

10 

-16.1 

57 

-1.0 

41 

-3.9 

25 

-8.2 

9 

-17.0 

56 

-1.2 

40 

-4.1 

24 

-8.5 

8 

-18.1 

55 

-1.3 

39 

-4.3 

23 

-8.9 

7 

-19.2 

54 

-1.5 

38 

-4.5 

22 

-9.3 

6 

-20.6 

53 

-1.6 

37 

-4.8 

21 

-9.7 

5 

-22.1 

52 

-1.8 

36 

-5.0 

20 

-10.1 

4 

-24.1 

51 

-2.0 

35 

-5.2 

19 

-10.5 

3 

-26.6 

50 

-2.1 

34 

-5.5 

18 

-11.0 

2 

-30.1 

49 

-2.3 

33 

-5.8 

17 

-11.5 

1 

-36.1 

AUDxVOL  =  0  corresponds  to  a  dB  value  of  minus  infinity.  If  AUDxVOL 
=  64,  then  a  digital  value  of  127  corresponds  to  an  output  voltage  of 
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about  400  millivolts,  and  -128  corresponds  to  -400  millivolts.  A  change 
of  1  LSB  causes  about  a  3  millivolt  variation  in  the  output  voltage. 

Example  programs 

Program  1:  Creating  a  simple  sine  wave 

This  program  creates  a  sine  wave  tone  with  a  frequency  of  440  Hz.  The 
sample  table  presented  in  the  text  is  used.  The  largest  portion  of  the 
program  is  used  to  allocate  chip  RAM  for  the  audio  data  list.  The  sound 
is  produced  over  channel  0  until  the  mouse  button  is  pressed.  The 
program  then  releases  the  occupied  memory. 

.***  create  a  simple  sinewave  *** 

; Custom  chip  registers 

intena  =  $9A      ; Interrupt  enable  register  (write) 

dmacon  =  $96      /DMA  control  register  (write) 

; Audio-Register 

audOlc  =  $A0  ;Address  of  audio  data  list 

audOlen  =  $A4  /Length  of  audio  data  list 

audOper  =  $A6  /Sampling  period 

audOvol  =  $A8  /Volume 

adkcon  =  $9E  /Control  register  for  modulation 

/CIA-A  Port  register  A  (mouse  button) 
ciaapra  =  $bfe001 

/Exec  Library  Base  Offsets 

AllocMem  =  -30-168     /ByteSize,Requirements/dO,dl 

FreeMem  =  -30-180      /MemoryBlock, ByteSize/al,d0 

/Other  labels 

ALsize  =  ALend  -  ALstart    /Length  of  audio  data  list 

Execbase  =  4 

chip  =  2  /Allocate  chip  RAM 

/***  Initialization  *** 

start : 

/Allocate  memory  for  audio  data  list 

move . 1  Execbase , a6 

moveq   #ALsize,dO      /Size  of  audio  data  list 

moveq   #chip, dl 

jsr     AllocMem(a6)     /Allocate  memory 
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beq 


Ende 


.•Error  ->  End  program 


;Copy  audio  data  list  in  chip  RAM 
move.l   dO,aO  ; Address  in  chip  RAM 

move.l  #ALstart,al     ,-Address  in  program 
moveq   #ALsize-l,dl     ;Loop  counter 

Loop:     move.b  (al)+,(aO)+  ;Data  list  in  chip  RAM 
dbf      dl,Loop 

;***  Main  program 

; Initialize  audio  registers 
lea     $DFF000,a5 

move.w  #$000f ,dmacon(a5)  ;Audio  DMA  off 
move.l   d0,aud01c(a5)      ;Set  address  of  data  list 
move.w  #ALsize/2,aud01en(a5)  ;Length  in  words 
move.w   #32,aud0vol(a5)    ;Half  volume 
move.w  #508,aud0per (a5)   ; Frequency:  440  Hz 
move.w  #$00ff ,adkcon(a5)  .-Disable  modulation 

.•Enable  audio  DMA 
move.w  #$8201,dmacon(a5)  .-Channel  0  on 

;Wait  for  a  mouse  button 
wait:   btst  #6,ciaapra 
bne     wait 

; Disable  audio  DMA 
move.w  #$0001,dmacon(a5)  /Channel  0  off 

;***  End  of  program  *** 

move.l  d0,al  ,-Address  of  data  list 

moveq   #ALsize,d0  ;Length 

jsr     FreeMem(a6)  ,-Release  assigned  memory 


Ende:  clr 

.1  dO 

rts 

; Audio  data  list 

ALstart : 

dc.b 

0,49 

dc.b 

90,117 

dc.b 

127,117 

dc.b 

90,49 

dc.b 

0,-49 

dc.b 

-90,-117 

dc.b 

-127,-117 

dc.b 

-90,-49 
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ALend: 

; Program  end 
end 


Program  2:  Sine  wave  tone  with  vibrato 

This  program  is  an  extension  of  the  previous  one.  The  same  sine  wave 
tone  is  output,  but  this  time  over  channel  1.  Channel  0  modulates  the 
frequency  of  channel  1  and  creates  the  vibrato  effect.  The  data  for  the 
vibrato  represents  a  digitized  sine  wave  whose  zero  point  has  the  value 
of  the  sampling  period  of  a  standard  A  (i.e.,  508). 


;***  Creating  a  vibrato  *** 

/Custom  chip  register 

INTENA  =  $9A  /Interrupt  enable  register  (write) 
DMACON  =  $9  6  ;DMA  control  register  (write) 

;Audio  registers 

AUDOLC   =  $A0  ;Address  of  audio  data  list 

AUDOLEN  =  $A4  .-Length  of  audio  data  list 

AUDOPER  =  $A6  ; Sampling  period 

AUDOVOL  =  $A8  ; Volume 

AUD1LC  =  $B0 
AUD1LEN  =  $B4 
AUD1PER  =  $B6 
AUD1VOL  =  $B8 

ADKCON  =  $9E  /Control  register  for  modulation 

;CIA-A  Port  register  A  (mouse  button) 

CIAAPRA  =  $bfe001 

;Exec  Library  Base  Offsets 

AllocMem  =  -30-168  ;ByteSize, Requirements /d0,dl 
FreeMem  =  -30-180  ;MemoryBlock,ByteSize/al,dO 

/Other  labels 

Execbase  =  4 

chip     =  2     /Allocate  chip  RAM 

Vibsize  =  Vibend  -  Vibstart  /Length  of  vibrato  table 
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ALsize  =  ALend  -  ALstart  ;Length  of  audio  data  list 
Size  =  ALsize  +  Vibsize     ;Total  length  of  both  lists 


;***  Initialization  *** 
start : 

; Allocate  memory  for  data  lists 

move . 1  Execbase , a  6 

move.l  #Size,dO        ;Length  of  both  lists 

moveq  #chip,dl 

jsr  AllocMem(a6)    /Allocate  memory 

beq  Ende 

;Copy  audio  data  list  in  chip  RAM 

move.l   dO,aO  ; Address  in  chip  RAM 

move.l   #ALstart,al     ;Address  in  program 
move.l   #Size-l,dl      ;Loop  counter 

Loop:     move.b  (al)  +  ,(aO)+  .-Lists  in  chip  RAM 
dbf     dl , Loop 

;***  Main  program 

; Initialize  audio  registers 

move.l  dO,dl  ; Audio  data  list  address 

add.l  #ALsize,dl     .-Address  of  vibrato  table 

lea  $DFF000,a5 

move.w  #$000f ,dmacon(a5)  ,-Audio  DMA  off 

move.l  dl,aud01c(a5)   ;Set  to  vibrato  table 

move.w  #Vibsize,aud01en(a5)  ,-Length  of  vibrato  table 

move.w  #8961,aud0per(a5)       ;Vibrato  frequency 

move.l  d0,audllc(a5)  ; Channel  1  from  audio  data  list 
move.w  #ALsize,audllen(a5)  ,-Length  of  audio  data  list 
move.w  #32,audlvol(a5)       ,-Half  volume 

move.w  #$00FF,adkcon(a5)  ,-Disable  other  modulation 
move.w  #$8010,adkcon(a5)  ,-Channel  0  modulates  period  from 

; channel  1 

; Audio  DMA  on 

move.w  #$8203,dmacon(a5)  .-Channels  0  and  1  on 
;Wait  for  a  mouse  button 
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wait:    btst  #6,ciaapra 
bne     wait 

; Audio  DMA  off 

move.w  #$0003,dmacon(a5)  ;Channels  0  and  1  off 

,-***  End  program  *** 


move .1   dO , al 
move.l   #Size,dO 
jsr     FreeMem(a6) 

Ende:  clr.l  dO 
rts 

; Audio  data  list 


; Address  of  lists 

; Length 

; Release  memory 


ALstart : 

dc.b 

0,49 

dc.b 

90,117 

dc.b 

127,117 

dc.b 

90,49 

dc.b 

0,-49 

dc.b 

-90,-117 

dc.b 

-127,-117 

dc.b 

-90,-49 

ALend: 

; Vibrato 

table 

Vibstart : 

dew    508,  513  ,  518,  522,  524,  525,  524,  522,  518,  513 

dew    508,503,498,494,492,491,492,494,498,503 
Vibend : 
; Program  end 

end 

11.7.10      Mouse,  Joystick  and  Paddles 

Mouse,  joystick  and  paddles  ~  all  of  these  can  be  connected  to  the 
Amiga.  We'll  go  through  them  in  order,  together  with  the  corresponding 
registers.  The  pin  assignment  of  the  game  ports,  to  which  all  of  these 
input  devices  are  connected,  can  be  found  in  the  section  on  interfaces. 
Let's  start  with  the  mouse: 
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The  mouse 

The  mouse  is  the  most-often  used  input  device.  It's  an  important  device 
for  using  the  user-friendly  interfaces  of  the  Amiga.  But  how  does  it  work 
and  how  is  the  mouse  pointer  on  the  screen  created  and  moved? 

If  you  turn  over  the  mouse,  you'll  see  a  rubber-coated  metal  ball  that 
turns  when  the  mouse  is  moved.  These  rotations  of  the  ball  are 
transferred  to  two  shafts,  situated  at  right  angles  to  each  other  so  that 
one  turns  when  the  mouse  is  moved  along  the  X  axis  and  the  other  when 
the  mouse  is  moved  along  the  Y  axis.  If  the  mouse  is  moved  diagonally, 
both  shafts  rotate  corresponding  to  the  X  and  Y  components  of  the 
mouse  movement.  Unfortunately,  rotating  shafts  don't  help  the  Amiga 
when  it  wants  to  determine  the  position  of  the  mouse.  The  mechanical 
movement  must  be  converted  into  electrical  signals. 

A  wheel  with  holes  around  its  circumference  is  attached  to  the  end  of 
each  shaft  for  this  purpose.  When  it  rotates  it  repeatedly  breaks  a  beam 
of  light  in  an  optical  coupler.  The  signal  that  results  from  this  is  amplified 
and  sent  out  over  the  mouse  cable  to  the  computer.  Now  the  Amiga  can 
tell  when  and  at  what  speed  the  mouse  is  moved.  But  it  still  doesn't 
know  in  what  direction  (i.e.,  left  or  right,  forward  or  backward). 

A  little  trick  solves  this  problem.  Two  optical  couplers  are  placed  on  each 
wheel,  set  opposite  each  other  and  offset  by  half  a  hole.  If  the  disk 
rotates  in  a  given  direction,  one  light  beam  is  always  broken  before  the 
other.  If  the  direction  is  reversed,  the  order  of  the  two  signals  from  the 
optical  coupler  changes  accordingly.  This  allows  the  Amiga  to  determine 
the  direction  of  the  movement. 

Therefore,  the  mouse  returns  four  signals,  two  per  shaft.  They  are  called 
Vertical  Pulse,  Vertical  Quadrature  Pulse,  Horizontal  Pulse  and  Horizontal 
Quadrature  Pulse. 

The  next  figure  shows  the  phase  relationship  of  the  horizontal  pulse  (H) 
and  horizontal  quadrature  pulse  (HQ)  signals,  but  it  also  holds  for  the 
vertical  signals.  It's  easy  to  see  how  H  and  HQ  differ  from  each  other 
depending  on  the  direction  of  movement.  The  Amiga  performs  logical 
operations  on  these  two  signals  to  obtain  two  new  signals,  XO  and  XI. 
XI  is  an  inverted  HQ,  and  XO  arises  from  an  exclusive  OR  of  H  and  HQ 
(i.e.,  XO  is  1  whenever  H  and  HQ  are  at  different  levels). 
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With  these  two  signals  the  Amiga  controls  a  6-bit  counter  which  counts 
up  or  down  on  XI  depending  on  the  direction.  Together  with  XO  and  XI 
an  8-bit  value  is  formed  which  represents  the  current  mouse  position. 

If  the  mouse  is  moved  right  or  down,  the  counter  is  incremented.  If  the 
mouse  is  moved  left  or  up,  it  is  decremented. 

Denise  contains  four  such  counters,  two  per  game  port,  since  a  mouse 
can  be  connected  to  each  one.  They  are  called  JOYDATO  and  JO  YD  ATI: 

JOY0DAT$00A  -  JOY1DAT$OOC 

(mouse  on  game  port  0)  -  (mouse  on  game  port  1) 


Bit  no.:       15      14     13      12      11      10     9       8       7       6       5       4 3       2 1        0 
Function:    Y7     Y6     Y5     Y4     Y3     Y2     Y1     Y0     X7     X6     X5     X4     X3     X2X1X0 


Both  registers  are  read-only. 

YO-7  Counter  for  vertical  mouse  movements  (Y  direction) 

HO-7  Counter  for  horizontal  mouse  movements  (X  direction) 

The  mouse  creates  two  hundred  count  pulses  per  inch,  or  about  79  per 
centimeter,  which  means  that  the  limit  of  the  mouse  counter  is  soon 
reached.  Eight  bits  yield  a  count  range  from  0  to  255.  Moving  the  mouse 
over  four  centimeters  overflows  the  counters.  This  can  occur  when 
counting  up  (the  counter  jumps  from  255  to  0)  as  well  as  counting  down 
(the  counter  jumps  from  0  to  255).  Therefore,  the  count  registers  must  be 
read  at  given  intervals  to  see  if  an  overflow  or  underflow  has  occurred. 
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1 .  Right  movement 

h_I~ 


2.  Left  movement 

»_T~ 


HQ 

XO 

X1 


j — i r 


Truth  tables  for  XO  and  X1: 


H   HO 

XO 

0      0 

0 

0      1 

1 

1      0 

1 

1    1 

0 

~1_ 

HQ   |C1 


The  mouse  signals 

The  operating  system  usually  does  this  during  the  vertical  blanking 
interrupt.  This  is  based  on  the  assumption  that  the  mouse  is  not  moved 
more  than  127  count  steps  between  two  successive  reads.  The  new 
counter  state  is  compared  with  the  last  value  read.  If  the  difference  is 
greater  than  127,  then  the  counter  overflowed  and  the  mouse  was  moved 
right  or  down.  If  it's  less  than  -127,  an  underflow  occurred  corresponding 
to  a  mouse  movement  left  or  up. 


Old                   New 

Actual 

Under-/ 

counter  state      counter  state 

Difference 

mouse  movement 

Overflow 

100                     200 

-100 

+100 

No 

200                     100 

+100 

-100 

No 

50                       200 

-150 

-105 

Underflow 

200                     50 

+150 

+105 

Overflow 

Difference  =  old  counter  state  - 

new  counter  state 

If  an  underflow  occurred,  the  actual  mouse  movement  is  calculated  as 
follows: 
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1  -255  -  difference,  or  in  numbers:  -255  -  (50-200)  =  -105     | 

For  an  overflow: 

|255  -  difference,  or  in  numbers:  255  -  (200-50)  =  +105       | 

A  positive  mouse  movement  corresponds  to  a  movement  right  or  up,  a 
negative  value  to  left  or  down. 

The  mouse  counters  can  also  be  set  through  software.  A  value  can  be 
written  to  the  counter  through  the  JOYTEST  register.  JOYTEST  operates 
on  both  game  ports  simultaneously,  meaning  that  the  horizontal  and 
vertical  counters  of  both  mouse  counters  are  initialized  with  the  same 
value  (JOY0DAT  =  JOY1DAT). 

JOYTEST  $036  (write-only) 


Bit  no.:       15      14      13      12      11      10      9       8       7        6       5       4       3       2        1        0 
Function:    Y7     Y6     Y5     Y4     Y3     Y2     xx     xx     X7     X6     X5     X4     X3     X2     xx     xx 


As  you  can  see,  only  the  high-order  six  bits  of  the  counters  can  be 
affected.  This  makes  sense  when  you  remember  that  the  lower  two  bits 
are  taken  directly  from  the  mouse  signals  and  aren't  in  an  internal  memory 
location  that  can  be  changed. 

The  joysticks 

When  you  look  at  the  pin-out  of  the  game  ports,  you  see  that  the  four 
direction  lines  for  the  joysticks  occupy  the  same  lines  as  those  for  the 
mouse.  Therefore,  it  seems  reasonable  that  they  can  also  be  read  with  the 
same  registers.  In  fact,  the  joystick  lines  are  processed  exactly  like  the 
mouse  signals  (i.e.,  each  pair  of  lines  is  combined  into  the  X0  and  XI  or 
Y0  and  Yl  bits). 

The  joystick  position  can  be  determined  from  these  four  bits: 


Joystick  right 
Joystick  left 
Joystick  backward 
Joystick  forward 


X1  =  1  (bit  1  JOYxDAT) 

Y1  =  1  (bit  9  JOYxDAT) 

X0  EOR  X1  =  1  (bits  0  and  1  JOYxDAT) 

Y0  EOR  Y1  =  1  (bits  8  and  9  JOYxDAT) 


In  order  to  detect  whether  the  joystick  has  been  moved  backward  or 
forward,  you  must  take  the  exclusive  OR  of  X0  and  XI  or  Y0  and  Yl, 
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respectively.  If  the  result  is  1 ,  the  joystick  is  in  the  position.  The  following 
assembly  language  routine  reads  the  joystick  on  game  port  1: 


Test Joystick: 
MOVE.W  $DFF00C,  DO 
BTST  #1,  DO 
BNE  RIGHT 
BTST  #9,  DO 
BNE  LEFT 
MOVE.W  D0,D1 
LSR.W  #1,D1 
EOR.W  D0,D1 
BTST  #0,  Dl 
BNE  BACK 
BTST  #8,  Dl 
BNE  FORWARD 
BRA  MIDDLE 


;Move  JOY1DAT  to  DO 

;Test  bit  no.  1 

;Set?  If  so,  joystick  right 

;Test  bit  no.  9 

;Set?  If  so,  joystick  left 

;Copy  DO  to  Dl 

;Move  Yl  and  XI  to  position  of  Y0  and  XO 

; Exclusive  OR:  Yl  EOR  Y0  and  XI  EOR  XO 

;Test  result  of  XI  EOR  XO 

; Equal  1?  If  so,  joystick  backward 

;Test  result  of  Yl  EOR  Y0 

; Equal  1?  If  so,  joystick  forward 

,-Joystick  is  in  middle  position 

The  exclusive  OR  operation  is  performed  as  follows  in  this  program: 

A  copy  of  the  JOY  1  DAT  register  (previously  moved  to  DO)  is  placed  in 
Dl  and  is  shifted  one  bit  to  the  right.  Now  XI  in  Dl  and  XO  in  DO  have 
the  same  bit  position,  as  do  Yl  and  Y0.  An  EOR  between  DO  and  Dl 
exclusive  ORs  Y0  with  Yl  and  XO  with  XI.  Then  all  you  have  to  do  is 
test  the  result  in  Dl  with  the  appropriate  BTST  commands. 

This  program  does  not  support  diagonal  joystick  positions. 
The  paddles 

The  Amiga  has  two  analog  inputs  per  game  port,  to  which  variable 
resistors  called  potentiometers  can  be  connected.  These  have  in  each 
position  a  given  resistance,  which  can  be  determined  by  the  hardware  in 
Paula.  A  paddle  contains  such  a  potentiometer  which  can  be  set  with  a 
knob.  Analog  joysticks  also  work  this  way.  One  potentiometer  for  the  X 
and  one  for  the  Y  direction  determine  the  joystick  position  exactly. 

Two  registers  contain  the  four  8-bit  values  of  the  analog  inputs, 
POTODAT  for  game  port  0  and  POT1DAT  for  game  port  1 : 
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POT0DAT$012  POT1DAT$014 


Bit  no.:       T5      14"      13      12      TT      10      9        8       1       6       5       4       3       2        1        <T~ 
Function:    Y7     Y6     Y5     Y4     Y3     Y2     Y1      YO     X7     X6     X5     X4     X3     X2     X1      XO 


Both  registers  are  read-only. 

How  is  the  resistance  measured?  Since  a  computer  can  process  only 
digital  signals,  it  needs  a  special  circuit  to  convert  any  analog  signals  it 
wants  to  work  with.  On  the  Amiga  the  value  of  external  resistance  is 
determined  as  follows: 

The  potentiometers  have  a  maximum  resistance  of  470  kilo  Ohms 
(±10%).  One  side  is  connected  to  the  +5-volt  output  and  the  other  to 
one  of  the  four  paddle  inputs  of  the  game  ports.  These  lead  internally  to 
the  corresponding  inputs  of  Paula  and  to  one  of  four  capacitors 
connected  between  the  input  and  ground. 

The  measurement  is  started  by  means  of  a  special  start  bit.  Paula  pulls  all 
paddle  inputs  briefly  to  ground,  discharging  the  capacitors.  At  this  time 
the  counters  in  the  POTxDAT  registers  are  also  cleared.  After  this  the 
counters  increment  by  one  with  each  screen  line,  while  the  capacitors  are 
slowly  recharged  through  the  resistors.  When  the  capacitor  voltage 
exceeds  a  given  value,  the  corresponding  counter  is  stopped.  The 
counter  state  corresponds  exactly  to  the  size  of  the  resistance.  Small 
resistances  yield  low  counter  values,  greater  ones  yield  higher  values. 

The  start  bit  is  located  in  the  POTGO  register: 

POTGO  $034  (write-only)  -  POTGOR  $016  (read-only) 


Bit  no.      Name 


Function 


15 

OUTRY 

14 

DATRY 

13 

OUTRX 

12 

DATRX 

11 

OUTLY 

10 

DATLY 

9 

OUTLX 

8 

DATLX 

7-1 

0 

START 

Switch  game  port  1  POTY  to  output 

Game  port  1  POTY  data  bit 

Switch  game  port  1  POTX  to  output 

Game  port  1  POTX  data  bit 

Switch  game  port  0  POTY  to  output 

Game  port  0  POTY  data  bit 

Switch  game  port  0  POTX  to  output 

Game  port  0  POTX  data  bit 

Unused 

Discharge  capacitors,  begin  measurement 


A  write  access  to  POTGO  clears  both  POTxDAT  registers. 
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Normally  you  set  the  START  bit  to  1  in  the  vertical  blanking  gap.  Then 
while  the  picture  is  being  displayed,  the  capacitors  charge  up,  reach  the 
set  value  and  stop  the  counters.  The  valid  potentiometer  readings  can 
then  be  taken  from  the  POTxDAT  registers  in  the  next  vertical  blanking 
gap. 

The  four  analog  inputs  can  also  be  programmed  as  normal  digital 
input/output  lines.  The  corresponding  control  and  data  bits  are  found 
together  with  the  START  bit  in  the  POTGO  register.  Each  line  can  be 
individually  set  to  an  output  with  the  OUTxx  bits  (OUTxx  =  1). 

This  separates  them  from  the  control  circuit  of  the  capacitors  and  causes 
the  value  in  the  DATxx  bit  of  POTGO  to  be  output  over  them.  Reading  a 
DATxx  bit  in  POTGOR  always  returns  the  current  state  of  the  line.  The 
following  must  be  noted  if  the  analog  ports  are  used  as  outputs: 

Since  the  four  analog  ports  are  internally  connected  to  the  capacitors  for 
resistance  measurement  (47  nF),  it  can  take  up  to  300  microseconds  for 
the  line  to  assume  the  desired  level  due  to  the  charging/discharging  of 
the  capacitor  required. 

The  input  device  buttons 

Each  of  the  three  input  devices  mentioned  so  far  has  one  or  more 
buttons.  The  following  table  shows  which  registers  contain  the  status  of 
the  mouse,  paddle  and  joystick  buttons: 
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Game  port  0: 


Left  mouse  button 
Right  mouse  button 
(Third  mouse  button 
Joystick  fire  button 
Left  paddle  button 
Right  paddle  button 


CIA-A,  parallel  port  A,  port  bit  6        ~~ 

POTGOR,  DATLY 

POTGOR,  DATLX) 

CIA-A,  parallel  port  A,  port  bit  6 

JOYODAT,  bit  9  (1  =  button  pressed) 

JOYODAT,  bit  1  (1  =  button  pressed) 


Game  port  1 : 


Left  mouse  button 
Right  mouse  button 
(Third  mouse  button 
Joystick  fire  button 
Left  paddle  button 
Right  paddle  button 


CIA-A,  parallel  port  A,  port  bit  7 

POTGOR,  DATRY 

POTGOR,  DATRX) 

CIA-A,  parallel  port  A,  port  bit  7 

JOY1DAT,  bit  9  (1  =  button  pressed) 

JOY1DAT,  bit  1  (1  =  button  pressed) 


Unless  otherwise  indicated,  all  bits  are  active-zero,  meaning  0  =  button 
pressed. 


11.7.11      The  Serial  Interfaces 


As  we  discussed  earlier,  the  Amiga  has  a  standard  RS-232  interface.  The 
various  lines  of  this  connector  can  be  divided  into  two  signal  groups: 

1.  The  serial  data  lines 

2.  The  handshake  lines 

First  about  number  2:  The  RS-232  interface  has  a  number  of  handshake 
lines.  Normally  they  are  not  all  used.  However,  the  behavior  of  these 
signals  is  not  always  the  same  from  one  RS-232  device  to  another. 

Now  to  number  1: 

All  data  transfer  takes  place  over  the  two  data  lines.  The  RXD  line 
receives  the  data  and  it's  sent  out  over  TXD.  RS-232  communication  can 
take  place  in  two  directions  at  once  when  two  devices  are  connected 
together  through  RXD  and  TXD.  The  RXD  of  one  device  is  connected  to 
the  TXD  of  the  other,  and  vice  versa. 
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Principle  of  serial  RS-232  data  transfer 
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The  RS-232  data  transfer 

Since  only  one  line  is  available  for  the  data  transfer  in  each  direction,  the 
data  words  must  be  converted  into  a  serial  data  stream  which  can  then  be 
transmitted  bit  by  bit.  No  clock  lines  are  provided  in  the  RS-232 
standard.  So  that  the  receiver  knows  when  it  can  read  the  next  bit,  the 
time  per  bit  must  be  constant  (i.e.,  the  speed  at  which  the  data  is  sent  and 
received  must  be  defined).  This  speed  is  called  the  baud  rate,  and  it 
determines  the  number  of  bits  transferred  per  second.  For  example, 
common  baud  rates  are  300,  1200,  2400,  4800  and  9600  baud.  You're 
not  limited  to  these  baud  rates,  but  when  using  strange  baud  rates, 
remember  that  the  sender  and  receiver  must  actually  match. 

One  more  thing  required  for  successful  transfer  is  that  the  receiver  must 
know  when  a  byte  starts  and  ends.  The  above  figure  shows  the  timing  of 
the  transmission  of  a  data  byte  on  one  of  the  data  lines.  Each  byte  begins 
with  a  start  bit,  which  is  no  different  from  the  normal  data  bits  but  always 
has  a  value  of  0.  Following  this  are  the  data  bits  in  the  order  LSB  to 
MSB.  At  the  end  are  one  or  two  stop  bits,  which  have  the  value  1.  The 
receiver  recognizes  the  transition  from  one  byte  to  the  next  by  the  level 
change  from  1  to  0  that  occurs  when  a  start  bit  follows  a  stop  bit. 

The  component  that  performs  this  serial  transfer  is  called  a  Universal 
Asynchronous  Receiver/Transmitter,  or  UART.  In  the  Amiga  it  is 
contained  in  Paula,  and  its  registers  are  in  the  custom  chip  register  area: 
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The  UART  registers 

SERPER  $032  (write-only) 


Bit  no.       Name 


Function 


15 
0-14 


LONG 
RATE 


Set  length  of  receive  data  to  9  bits 

This  15-bit  number  contains  the  baud  rate 


SERDAT  $030  (write-only) 
SERDAT  contains  the  send  data. 
SERDATR  $018  (read-only) 


Bit  no. 

Name 

Function 

15 

OVRUN 

Overrun  of  receive  shift  register 

14 

RBF 

Receive  buffer  full 

13 

TBE 

Transmit  buffer  empty 

12 

TSRE 

Transmit  shift  register  empty 

11 

RXD 

Corresponds  to  level  on  RXD  line 

10 

... 

Unused 

9 

STP 

Stop  bit 

8 

STP  or  DB8 

Depends  on  data  length 

7 

DB7 

Receive  data  buffer  bit  7 

6 

DB6 

Receive  data  buffer  bit  6 

5 

DB5 

Receive  data  buffer  bit  5 

4 

DB4 

Receive  data  buffer  bit  4 

3 

DB3 

Receive  data  buffer  bit  3 

2 

DB2 

Receive  data  buffer  bit  2 

1 

DB1 

Receive  data  buffer  bit  1 

0 

DBO 

Receive  data  buffer  bit  0 

One  bit  in  the  ADKCON  register  belongs  to  UART  control: 

ADKCON  $09E  (write)  ADKCONR  $010  (read)  SERIELL 

Bit  no.  1 1:  UARTBRK  -  interrupts  the  serial  output  and  sets  TXD 

to  0. 

Data  transfer  with  the  Amiga  UART 

Receiving 

The  reception  of  the  serial  data  takes  place  in  two  stages.  The  bits 
arriving  on  the  RXD  pin  are  received  into  the  shift  register  at  the  baud 
rate  and  are  combined  there  into  a  parallel  data  word.  When  the  shift 
register  is  full,  its  contents  are  written  into  the  receiver  data  buffer.  It  is 
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then  free  for  the  next  data.  The  processor  can  read  only  the  receiver  data 
buffer,  not  the  shift  register.  The  corresponding  data  bits  in  the 
SERDATR  register  are  DBO  to  DB7  or  DB8. 

The  Amiga  can  receive  both  eight  and  nine-bit  data  words.  The  UART 
can  be  set  to  9-bit  words  with  the  LONG  bit  (=1)  in  the  SERPER  register. 

The  data  length  determines  the  format  in  the  SERDATR  register.  With  9 
bits,  bit  8  of  SERDATR  contains  the  ninth  data  bit,  while  the  stop  bit  is 
found  in  bit  9.  With  eight  data  bits,  bit  8  contains  the  stop  bit.  If  two  stop 
bits  are  present,  the  second  lands  in  bit  9. 

The  state  of  the  receiver  shift  register  and  the  data  buffer  is  given  by  two 
signal  bits  in  SERDATR: 

RBF  stands  for  Receive  Buffer  Full.  As  soon  as  a  data  word  is  transferred 
from  the  shift  register  to  the  buffer,  this  bit  changes  to  1  and  thereby 
signals  the  processor  that  it  should  read  the  data  out  of  SERDATR. 

This  bit  also  exists  in  the  interrupt  registers  (RBF,  INTREQ/INTEN  bit  11). 
After  the  processor  has  read  the  data,  it  must  reset  RBF  in  INTREQ.  The 
bit  then  returns  to  0  in  SERDATR  and  in  INTREQR. 

MOVE.W  #$0800,$DFFOOO+INTREQ      ,-Clears  RBF  in  INTREQ  and  SERDATR 

If  this  is  not  done  and  the  shift  register  has  received  another  complete 
data  word,  the  UART  sets  the  OVRUN  bit.  This  signals  that  no  more  data 
can  be  received  because  both  the  buffer  (RBF  =1)  and  the  shift  register 
(OVRUN  =  1)  are  full.  OVRUN  returns  to  0  when  RBF  is  reset.  RBF  then 
jumps  back  to  1  because  the  contents  of  the  shift  register  are  immediately 
transferred  to  DBO  through  DB8  to  free  the  shift  register  for  more  data. 

Transmitting 

The  sending  process  also  takes  place  in  two  stages.  The  transmit  data 
buffer  is  found  in  the  SERDAT  register.  As  soon  as  a  data  word  is  written 
into  this  register  it  is  transferred  to  the  output  shift  register.  This  is 
signaled  by  the  TBE  bit.  TBE  stands  for  Transmit  Buffer  Empty  and 
indicates  that  SERDAT  is  ready  to  take  more  data.  TBE  is  also  present  in 
the  interrupt  registers  (TBE,  INTREQ/INTEN  bit  0).  Like  RBF,  TBF  must 
also  be  reset  in  the  INTREQ  register. 
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Once  the  shift  register  has  sent  the  data  word,  the  next  one  is 
automatically  loaded  from  the  transmitter  data  buffer.  If  this  is  empty,  the 
UART  sets  the  TSRE  bit  (Transmit  Shift  Register  Empty)  to  1.  This  bit  is 
reset  when  TBE  is  cleared. 

The  length  of  the  data  word  and  the  number  of  stop  bits  are  set  by  the 
format  of  the  data  in  SERDAT.  You  simply  write  the  desired  data  word  to 
the  lower  eight  or  nine  bits  of  SERDAT  with  one  or  two  stop  bits  (l's)  in 
front  of  it.  An  eight-bit  data  word  with  two  stop  bits  would  look  like  this, 
for  example: 


1       §       5       4       3       2       1        0~~ 
D7     D6     D5     D4     D3     D2     D1      DO 


Bit  no.:       15     14     13     12     11      9       8 

Function:    0       0       0       0       0       1        1 


DO  to  D7  are  the  eight  data  bits. 

The  two  ones  represent  the  desired  two  stop  bits.  With  a  nine-bit  data 
word  and  one  stop  bit  the  following  data  must  be  written  into  SERDAT: 


Bit  no.: 
Function: 

15 
0 

14 
0 

13      12      11      9        8        7 
0        0        0        1        D8     D7 

6 

D6 

5 

D5 

4 

D4 

3 
D3 

2 
D2 

1 
D1 

0 
DO 

Eight  bits  plus  one  stop  bit: 

Bit  no.: 
Function: 

15 
0 

14 
0 

13      12      11      9        8        7 
0        0        0       0        1        D7 

6 
D6 

5 
D5 

4 
D4 

3 

D3 

2 

D2 

1 
D1 

0 
DO 

The  LONG  bit  in  the  SERPER  register  affects  only  the  length  of  the  data 
received.  The  format  of  the  transmitted  data  is  determined  only  by  the 
value  in  the  SERDAT  register. 

Setting  the  baud  rate 

The  baud  rate  for  sending  and  receiving  data  must  be  written  to  the 
lower  15  bits  of  the  SERPER  register.  Unfortunately,  the  baud  rate 
cannot  be  set  directly.  You  must  select  the  number  of  bus  cycles 
between  two  bits  (1  bus  cycle  takes  2.79365  *  10-7  seconds).  If  a  bit  is 
to  be  output  every  n  bus  cycles,  the  value  n-1  must  be  written  to  the 
SERPER  register.  The  following  formula  can  be  used  to  calculate  the 
necessary  SERPER  value  from  the  baud  rate: 
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SERPER  =  - 1 

Baud  rate* 2.79365*  10-7 


For  example,  for  a  baud  rate  of  4800  baud: 
ISERPER  =  1/(4800*2.79365*10-7)-!=  1/0.00134-1=  744.74 
The  calculated  value  is  rounded  and  written  to  SERPER: 

MOVE.W  #745,$DFF000+SERPER  ;Set  SERPER,  LONG  =  0 

or 

MOVE.W  #$8000+745,  $DFFO0O+SERPER     ,-LONG  =  1 

1 1 .7.1 2      The  Disk  Controller 

The  hardware  control  of  the  disk  drives  is  divided  into  two  parts.  First 
there  are  the  control  lines  which  activate  the  desired  drive,  turn  the  motor 
on,  move  the  read/write  head,  etc.  They  all  lead  to  various  port  lines  of 
the  CIAs. 

Excluded  from  these  are  the  data  lines.  These  carry  the  data  from  the 
read/write  head  to  the  Amiga  and,  when  writing,  in  the  opposite  direction 
from  the  Amiga  to  the  diskette.  A  special  component  in  Paula,  the  disk 
controller,  handles  the  processing  of  the  data. 

It  has  its  own  DMA  channel  and  writes  or  reads  data  by  itself  to  or  from 
the  disk. 

Programming  the  disk  DMA 

Before  you  start  the  disk  DMA  you  must  be  sure  that  the  previous  disk 
DMA  is  finished.  If  one  interrupts  a  write  access  in  piogress,  the  data  on 
the  corresponding  track  can  be  destroyed.  Let's  assume  that  the  last  disk 
DMA  is  done. 

First  we  must  define  the  memory  address  of  the  data  buffer.  The  disk 
DMA  uses  one  of  the  usual  address  register  pairs  as  a  pointer  to  the  chip 
RAM.  The  registers  are  called  DSKPTH  and  DKSPTL: 
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$20  DSKPTH        Pointer  to  data  from/to  disk  Bits  16-20 
$22  DSKPTL        Pointer  to  data  from/to  disk  Bits  0-15. 


Next  the  DSKLEN  register  must  be  initialized.  It  is  constructed  as 
follows: 

DSKLEN  $024  (write-only) 


Bit  no. 


Name 


Function 


15 
14 
0-13 


DMAEN 
WRITE 
LENGTH 


Enable  disk  DMA 
Write  data  to  disk 
Number  of  data  words  to  be  transferred 


LENGTH  The  lower  14  bits  of  the  DSKLEN  register  contain  the 

number  of  data  words  to  be  transferred. 

WRITE  WRITE  =  1  switches  the  disk  controller  from  read  to 

write. 

DMAEN  When  DMAEN  is  set  to  1  the  data  transfer  begins. 

A  few  things  must  be  noted: 

1.  The  Disk  DMA  Enable  bit  in  the  DMACON  register  (DSKEN,  bit  4) 
must  also  be  set. 

2.  To  make  it  more  difficult  to  write  to  the  disk  accidentally,  the 
DMAEN  bit  must  be  set  twice  in  succession.  Only  then  does  the 
disk  DMA  begin.  Furthermore,  for  safety's  sake  the  WRITE  bit 
should  only  be  1  during  a  write  operation. 

An  orderly  initialization  sequence  for  disk  DMA  appears  as  follows: 

1.  Write  a  0  to  DSKLEN  to  turn  DMAEN  off. 

2.  If  DSKEN  in  DMACON  is  not  yet  set,  do  so  now. 

3 .  Store  the  desired  address  in  DSKPTH  and  DSKPTL. 

4.  Write  the  correct  value  for  LENGTH  and  WRITE  along  with  a  set 
DMAEN  bit  to  DSKLEN. 

5 .  Write  the  same  value  into  DSKLEN  again. 

6.  Wait  until  the  disk  DMA  is  done. 

7.  For  safety's  sake,  set  DSKLEN  back  to  zero. 
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The  DSKBLK  interrupt  (disk  block  finished,  bit  1  in  INTREQ/INTEN)  is 
provided  so  that  the  processor  knows  when  the  disk  controller  has 
transferred  the  number  of  words  defined  in  LENGTH.  It  is  generated 
when  the  last  data  word  is  read  or  written.  The  current  status  of  the  disk 
controller  can  be  read  in  the  DSKBYTR  register: 


DSKBYTR  $01 A  (read-only) 


Bit  no. 

Name 

Function 

15 

BYTEREADY 

Signals  that  the  data  byte  in  the  lower  eight  bits 
is  valid. 

14 

DMAON 

Indicates  whether  the  disk  DMA  is  enabled.  To 
make  DMAON  =  1 ,  both  DMAEN  in  DSKLEN 
and  DSKEN  in  DMACON  must  also  be  set. 

13 

DSKWRITE 

Indicates  the  status  of  WRITE  in  DSKLEN. 

12 

WORDEQUAL 

Disk  data  equals  DSKSYNC 

11-8 

Unused 

7-0 

DATA 

Current  data  byte  from  the  disk 

With  the  eight  DATA  bits  and  the  BYTEREADY  flag  you  can  read  the 
data  from  the  disk  with  the  processor  rather  than  through  DMA.  Each 
time  a  complete  byte  is  received  the  disk  controller  sets  the 
BYTEREADY  bit.  The  processor  then  knows  that  the  data  byte  in  the 
eight  DATA  bits  is  valid.  After  the  DSKBYTER  register  is  read  the 
BYTEREADY  flag  is  automatically  reset. 

Sometimes  we  don't  want  to  read  an  entire  track  into  memory  at  once.  In 
this  case  the  DMA  transfer  can  be  made  to  start  at  a  given  position.  To 
do  this,  write  the  data  word  at  which  you  want  the  disk  controller  to  start 
into  the  DSKSYNC  register: 

DSKSYNC  $07E  (write-only) 

DSKSYNC  contains  the  data  word  at  which  the  transfer  is  to  begin.  The 
disk  controller  then  starts  as  usual  after  the  disk  DMA  is  enabled  and 
reads  the  data  from  the  disk,  but  it  doesn't  write  it  into  memory.  Instead,  it 
continually  compares  each  data  word  with  the  word  in  DSKSYNC. 
When  the  two  match  it  starts  the  data  transfer,  which  then  continues  as 
usual.  The  disk  controller  can  be  programmed  to  wait  for  the 
synchronization  mark  at  the  start  of  a  data  block. 

The  WORDEQUAL  bit  in  the  DSKBYTER  register  becomes  1  as  soon  as 
the  data  read  matches  DSKSYNC.  Since  this  match  only  lasts  two  (or 
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four)  microseconds,  WORDEQUAL  is  also  set  only  during  this  time  span. 
An  interrupt  is  also  generated  at  the  same  time  WORDEQUAL  goes  to  1: 

Bit  12  in  the  INTREQ  and  INTEN  registers  is  the  DSKSYN  interrupt  bit. 
It  is  set  when  the  data  from  the  disk  matches  DSKSYNC. 

Setting  the  operating  parameters 

The  data  cannot  be  written  to  the  disk  in  the  same  format  as  found  in 
memory.  It  must  be  specially  coded.  Normally  the  Amiga  works  with 
MFM  coding.  However,  it  is  also  possible  to  use  GCR  coding.  Two  steps 
are  necessary  for  selecting  the  desired  coding: 

1.  An  appropriate  routine  must  encode  the  data  before  it  is  written  to 
disk  and  decode  the  data  as  it  is  read  from  disk. 

2.  The  disk  controller  must  be  set  for  the  appropriate  coding.  This  is 
done  with  certain  bits  in  the  ADKCON  register. 

ADKCON  $09E  (write)  ADKCONR  $010  (read)  DISK 


Bit  no. 

Name 

Function 

15 

SET/CLR 

Set  (SET/CLR=1 )  or  clear  bits 

14-13 

PRECOMP 

These  bits  contain  the  precompensation  value: 
Bit  14          Bit  13         PRECOMP  time 
0                0           Zero 

0  1            140  ns 

1  0           280  ns 
1                              560  ns 

12 

MFMPREC 

0  =  GCR,  1  =  MFM 

11 

UARTBRK 

Not  a  disk  controller  bit,  see  UART 

10 

WORDSYNC 

WORDSYNC  =  1  turns  on  synchronization  of  the 
disk  controller  according  to  the  word  in  the 
DSKSYNC  register. 

9 

MSBSYNC 

MSBSYNC  =  1  enables  GCR  synchronization 

8 

FAST 

Disk  controller  clock  rate: 

FAST=1 : 2  microseconds/bit  (MFM) 

FAST=0: 4  microseconds/bit  (GCR) 

7-0 

AUDIO 

These  bits  do  not  belong  to  the  disk  controller. 

The  disk  controller  data  registers 

As  usual  the  DMA  controller  transfers  data  in  memory  to  and  from  the 
appropriate  data  registers.  The  disk  controller  has  one  data  register  for 
data  read  from  the  disk  and  one  for  data  that  is  to  be  written  to  the  disk. 
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DSKDAT$026  (write-only) 

Contains  the  data  to  be  written  to  the  disk. 

DSKDAT  $008  (read-only) 

Contains  the  data  read  from  the  disk.  This  is  an  early-read  register  and 
cannot  be  read  by  the  processor. 
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Amiga  Desktop  Video  Power 


Amiga  desktop  Video  Power  is  the  most  complete  and  useful  guide 
desktop  video  on  the  Amiga. 
Amiga  Desktop  Video  Power 

covers  all  the  basics-  defining 
video  terms,  selecting  genlocks, 
digitizers,  scanners,  VCRs, 
camera  and  connecting  them  to 
the  Amiga. 

Justafewofthe  topics  described 
in  this  excellent  book: 

•  Now  includes  DCTV,  Video 
Toaster  info 

•  The  basics  of  video 

•  Genlocks 

•  Digitizers  and  scanners 

•  Frame  Grabbers/ 
Frame  Buffers 

•  How  to  connect  VCRs, 
VTRs,  and  cameras  to  the  Amiga 

•  Using  the  Amiga  to  add  or  incorporate  Special  Effects  to  a  video 

•  Paint,  Ray  Tracing,  and  3D  rendering  in  commercial  applications 

•  Animation 

•  Video  Titling 

•  Music  and  videos 

•  Home  videos 

•  Advanced  techniques 


to 


Item  #B122  ISBN  1-55755-122-7 
Suggested  retail  price:  $29.95 


- 

... 


■"■■■. 


\>  •  -. -■■• 


Includes 

companion 

diskette 


■:; 


See  your  local  dealer  or  order  TOLL  FREE  1-800-451-4319  in  US  &  Canada 


AmigaDOS:  Inside  &  Out  Revised 


AmigaDOS:  Inside  &  Out  covers  the  insides  of  AmigaDOS,  everything 
from  the  internal  design  to 
practical  applications. 

AmigaDOS  Inside  &  Out  will 
show  you  how  to  manage 
Amiga's  multitasking  cap- 
abilities more  effectively.  There 
is  also  a  detailed  reference 
section  which  helps  you  find 
information  in  a  flash,  both 
alphabetically  and  in  command 
groups.  Topics  include  getting 
the  most  from  the  AmigaDOS 
Shell  (wildcards  and  command 
abbreviations)  script  (batch) 
files  -  what  they  are  and  how  to 
write  them. 

More  topics  include: 


•  AmigaDOS  -  Tasks  and  handling 

•  Detailed  explanations  of  CLI  commands  and  their  functions 

•  In-depth  guide  to  ED  and  EDIT 

•  Amiga  devices  and  how  the  AmigaDOS  Shell  uses  them 

•  Customizing  your  own  startup-sequence 

•  AmigaDOS  and  multitasking 

•  Writing  your  own  AmigaDOS  Shell 
commands  in  C 

•  Reference  for  1 .2, 1 .3  and  2.0  commands 

•  Companion  diskette  included 


Item  #B125  ISBN  1-55755-125-1. 
Suggested  retail  price:  $24.95 
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Using  ARexx  on  the  Amiga 


Using  ARexx  on  the  Amiga  is  the  most  authoritative  guide  to  using  the 

popular  ARexx  programming 

language  on  the  Amiga.  It's  filled 

with    tutorials,    examples, 

programming  code  and  a 

complete  reference  section  that 

you  will  use  over  and  over  again. 

Using  ARexx  on  the  Amiga  is 

written  for  new  users  and 

advanced  programmers  of 

ARexx  by  noted  Amiga  experts 

Chris  Zamara  and  NickSullivan. 


Topics  include: 

•  What  is  Rexx/ARexx  - 
a  short  history 

•  Thorough  overview  of  all 
ARexx  commands  - 
with  examples 

•  Useful  ARexx  macros  for  controlling  software  and  devices 

•  How  to  access  other  Amiga  applications  with  ARexx 

•  Detailed  ARexx  programming  examples  for  beginners  and 
advanced  users 

•  Multitasking  and  inter-program  communications 

•  Companion  diskette  included 

•  And  much,  much  more! 


Item  #B114  ISBN  1-55755-114-6. 
Suggested  retail  price:  $34.95 
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Amiga  Machine  Language 


Amiga  Machine  Language  introduces  you  to  68000  machine  language 

programming  presented  in 

clear,  easy  to  understand  terms. 

If   you're   a   beginner,   the 

introduction  eases  you  into 

programming  right  away.  If 

you're        an        advanced 

programmer,  you'll  discover  the 

hidden  powers  of  your  Amiga. 

Learn   how  to  access  the 

hardware  registers,  use  the 

Amiga  libraries,  create  gadgets, 

work  with  Intuition  and  more. 

•  68000  microprocessor 
architecture 

•  68000  address  modes  and 
instruction  set 

•  Accessing  RAM,  operating 
system  and  multitasking 
capabilities 

•  Details  the  powerful  Amiga  libraries  for  access  to  AmigaDOS 

•  Simple  number  base  conversions 

•  Menu  programming  explained 

•  Speech  utility  for  remarkable  human  voice  synthesis 

•  Complete  Intuition  demonstration  program  including 
Proportional,  Boolean  and  String  gadgets 

Item  #B025  ISBN  1-55755-025-5.  Suggested  retail  price:  $19.95 
Companion  Diskette  available:  Contains  every  program  listed  in  the 
book-  complete,  error  free  and  ready  to  run!  Saves  you  hours  of  typing  in 
program  listings.  Available  only  from  Abacus.  Item  #S025.  $14.95 
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Amiga  C  for  Beginners 


Amiga  C  for  Beginners  is  an  introduction  to  learning  the  popular  C 

language.  Explains  the  language 

elements   using   examples 

specifically  geared  to  the  Amiga. 

Describes  C  library  routines,  how 

the  compiler  works  and  more. 

Topics  include: 

•  Beginner's  overview  of  C 

•  Particulars  of  C 

•  Writing  your  first  program 

•  The  scope  of  the  language 
(loops,  conditions,  functions, 
structures) 

•  Special  features  of  the 
C  language 

•  Input/Output  using  C 

•  Tricks  and  Tips  for 
finding  errors 

•  Introduction  to  direct 
programming  of  the  operating  system  (windows, 
screens,  direct  text  output,  DOS  functions) 

•  Using  the  LATTICE  and  AZTEC  C  compilers 

Item  #B045  ISBN  1-55755-045-X.  Suggested  retail  price:  $19.95 

Companion  Diskette  available:  Contains  every  program  listed  in  the 
book-  complete,  error  free  and  ready  to  run!  Saves  you  hours  of  typing  in 
program  listings.  Available  only  from  Abacus.  Item  #S045.  $14.95 


See  your  local  dealer  or  order  TOLL  FREE  1-800-451-4319  in  US  &  Canada 
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Amiga  Graphics:  Inside  &  Out 


Amiga  Graphics:  Inside  &  Out  will  show  you  the  super  graphic  features 

and  functions  of  the  Amiga  in 

detail.  Learn  thegraphicfeatures 

that  can  be  accessed  from 

AmigaBASIC    or    C.    The 

advanced  user  will  learn  how  to 

call  the  graphic  routines  from 

the  Amiga's  built-in  graphic 

libraries.     Learn     graphic 

programming  in  C  with  examples 

of  points,  lines,  rectangles, 

polygons,  colors  and  more. 

Complete  description  of  the 

Amiga  graphic  system-  View, 

ViewPort,  RastPort,  bitmap 

mapping,  screens  and  windows. 

Topics  include: 

•  Accessing  fonts  and  type 
styles  in  AmigaBASIC 

•  Loading  and  saving  IFF  graphics 

•  CAD  on  a  1024  x  1024  super  bitmap,  using  graphic 
library  routines 

•  Access  libraries  and  chips  from  BASIC-  4096  colors  at  once, 
color  patterns,  screen  and  window  dumps  to  printer 

•  Amiga  animation  explained  including  sprites,  bobs 
and  AnimObs,  Copper  and  blitter  programming 

Item  #B052  ISBN  1-55755-052-2.  Suggested  retail  price:  $34.95 
Companion  Diskette  available:  Contains  every  program  listed  in  the 
book-  complete,  error  free  and  ready  to  run!  Saves  you  hours  of  typing  in 
program  listings.  Available  only  from  Abacus.  Item  #S052.  $14.95 
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The  Best  Amiga  Tricks  &  Tips 


The  Best  Amiga  Tricks  &  Tips  is  a  great  collection  of  Workbench,  CLI 
and  BASIC  programming 
"quick-hitters",  hints  and 
application  programs.  You'll  be 
able  to  make  your  programs 
more  user-friendly  with  pull- 
down menus,  sliders  and  tables. 
BASIC  programmers  will  learn 
all  about  gadgets,  windows, 
graphic  fades,  HAM  mode,  3D 
graphics  and  more. 


The  Best  Amiga  Tricks  &  Tips 

includes  a  complete  list  of  BASIC 
tokens  and  multitasking  input 
and  a  fast  and  easy  print  routine. 
If  you're  an  advanced 
programmer,  you'll  discover  the 
hidden  powers  of  your  Amiga. 


•  Using  the  new  AmigaDOS,  Workbench  and  Preferences  1 .3 
and  Release  2.0 

•  Tips  on  using  the  new  utilities  on  Extras  1 .3 

•  Customizing  Kickstart  for  Amiga  1000  users 

•  Enhancing  BASIC  using  ColorCycle  and  mouse  sleeper 

•  Disabling  FastRAM  and  disk  drives 

•  Using  the  mount  command 

•  Writing  an  Amiga  virus  killer  program 

•  Disk  drive  operations  and  disk  commands 

•  Learn  machine  language  calls. 

Item  #  B107  ISBN  1-55755-107-3. 
Suggested  retail  price  $29.95 
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Amiga  BASIC:  Inside  and  Out 


Amiga  BASIC:  Inside  and  Out  is  the  definitive  step-by-step  guide  to 

programming  the  Amiga  in 

BASIC.  This  huge  volume 

should  be  within  every  Amiga 

user's  reach.  Every  Amiga 

BASIC    command    is   fully 

described  and  detailed.   In 

addition,  Amiga  BASIC:  Inside 

and  Out  is  loaded  with  real 

working  programs. 

Topics  include: 


Video  titling  for  high  quality 

object  animation 

Bar  and  pie  charts 

Windows 

Pull  down  menus 

Mouse  commands 

Statistics 

Sequential  and  relative  files 

Speech  and  sound  synthesis 


item  #B87X  ISBN  0-916439-87-9.  Suggested  retail  price:  $24.95 


Companion  Diskette  available:  Contains  every  program  listed  in  the 
book  complete,  error  free  and  ready  to  run!  Saves  you  hours  of  typing  in 
program  listings.  Available  only  from  Abacus.  Item  #S87X.  $14.95 
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Amiga  for  Beginners 


A  perfect  introductory  book  if  you're  a  new  or  prospective  Amiga  owner. 

Amiga      for      Beginners 

introduces  you  to  Intuition  (the 

Amiga's  graphic  interface),  the 

mouse,  windows  and  the 

versatile  CLI.  This  first  volume 

in  our  Amiga  series  explains 

every  practical  aspect  of  the 

Amiga  in  plain  English  with 

clear,  step-by-step  instructions 

for  common  Amiga  tasks. 

Amiga  for  Beginners  is  all  the 

info  you  need  to  get  up  and 

running. 

Topics  include: 


•  Unpacking  and  connecting 
the  Amiga  components 

•  Starting  up  your  Amiga 

•  Exploring  the  Extras  disk 

•  Taking  your  first  step  in  AmigaBASIC  programming  language 

•  AmigaDOS  functions 

•  Customizing  the  Workbench 

•  Using  the  CLI  to  perform  "housekeeping"  chores 

•  First  Aid,  Keyword,  Technical  appendixes 

•  Glossary 

Item  #B021  ISBN  1-55755-021-2.  Suggested  retail  price:  $16.95 


Companion  Diskette  not  available  for  this  book. 
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AssemPro 


Assembly  Language  Development  System  for  the  Amiga 

AssemPro  has  the  professional  features  that  advanced  programmers 
lookfor.  Like  syntax  error  search/ 


replace  functions  to  speed 
program  alterations  and  de- 
bugging. And  you  can  compile 
to  memory  for  lightning  speed. 
The  comprehensive  tutorial  and 
manual  have  the  detailed 
information  you  need  for  fast, 
effective  programming. 


AssemPro 


Amiga 


>  The  Professional 

Assembly  Language 
s| Development,  System 


AbacusHI 

A  Data  Becker  Product 


Features  include: 

•  Integrated  editor,  debugger, 
disassembler 
and  reassembler 

•  Runs  under  CLI 
and  Workbench 

•  Produces  either  PC- 
relocatable  or  absolute  code 

•  Create  custom  macros  for  nearly  any  parameter 

•  Error  search  and  replace  functions 

•  Menu-controlled  conditional  and  repeated  assembly 

•  Full  32-bit  arithmetic 

•  Advanced  debugger  with  68020  single-step  emulation 

•  Fast  assembly  to  either  memory  or  disk 

•  Written  entirely  in  machine  language 

•  Runs  on  any  Amiga  with  51 2K  or  more 

Item  #S030  ISBN  1-55755-030-1.  Suggested  retail  price:  $99.95 

Machine  language  programming  requires  a  solid  understanding  of  the  Amiga 's  hardware  and 
operating  system.  We  do  not  recommend  this  package  to  beginning  Amiga  programmers. 


See  your  local  dealer  or  order  TOLL  FREE  1-800-451-4319  in  US  &  Canada 
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reference  library  in  one  guide  for  all 
Amiga  500,  1 000,  2000,  2500  and 
3000  users.  Amiga  Intern  will  explain 
the  internals  of  the  Amiga  3000, 
Release  2.0  (Workbench  2.0)  of  the 
operating  system  and  Kickstart  2.0. 
Amiga  Intern  teaches  you  important 
information  about  the  ARexx 
programming  language  that  is 
bundled  with  all  Amiga  3000s. 
Amiga  intern  is  divided  into  three 
easy-to-use  sections  for  hardware, 
operating  system  and  ARexx 
programming.  If  you  are  interested 
in  the  Amiga  hardware  you'll  learn  all 
the  essentials  of  the  68030 
processor  and  its  environment. 
Amiga  Intern  also  contains  an 
extensive  reference  section  on 
Kickstart  2.0  and  much  more. 


US  $39.95/  CDN  $49.95 


The  definitive 
reference  book  for 
all  Amiga  computers 

A  short  overview  of  the  contents: 

Hardware: 

68030  and  68881/82  specifications 

MMU,  FPU  and  ECS 

Zorro  II  bus  system 

SCSI  I  controller 

FlickerFixer 
System  Software: 

Kickstart  2.0  innovations 

Workbench  2.0  innovations 

Overview  of  library  functions 

Program  samples 
ARexx: 
'  History  of  development 

Syntax  oriented  command  lists 

Basic  elements 

Special  language  elements 

Function  libraries 

Program  samples 


Computer  Book  Categor 

Computer:  Amiga 
vel:  Intermediate/Advanced 
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